582 lines
15 KiB
Markdown
582 lines
15 KiB
Markdown
---
|
|
title: "Command Line Interface"
|
|
description: "The pit tool"
|
|
weight: 40
|
|
type: "docs"
|
|
---
|
|
|
|
ƿit provides a command-line interface for managing packages, running scripts, and building applications.
|
|
|
|
## Basic Usage
|
|
|
|
```bash
|
|
pit <command> [arguments]
|
|
```
|
|
|
|
## General
|
|
|
|
### pit version
|
|
|
|
Display the ƿit version.
|
|
|
|
```bash
|
|
pit version
|
|
# 0.1.0
|
|
```
|
|
|
|
### pit help
|
|
|
|
Display help information.
|
|
|
|
```bash
|
|
pit help
|
|
pit help <command>
|
|
```
|
|
|
|
## Package Commands
|
|
|
|
These commands operate on a package's `cell.toml`, source files, or build artifacts.
|
|
|
|
### pit add
|
|
|
|
Add a dependency to the current package. Installs the package to the shop, builds any C modules, and updates `cell.toml`.
|
|
|
|
```bash
|
|
pit add gitea.pockle.world/john/prosperon # remote, default alias
|
|
pit add gitea.pockle.world/john/prosperon myalias # remote, custom alias
|
|
pit add /Users/john/work/mylib # local path (symlinked)
|
|
pit add . # current directory
|
|
pit add ../sibling-package # relative path
|
|
```
|
|
|
|
For local paths, the package is symlinked into the shop rather than copied. Changes to the source directory are immediately visible.
|
|
|
|
### pit build
|
|
|
|
Build C modules for a package. Compiles each C file into a per-file dynamic library stored in the content-addressed build cache at `~/.cell/build/<hash>`. A per-package manifest is written so the runtime can find dylibs by package name. C files in `src/` directories are compiled as support objects and linked into the module dylibs. Files that previously failed to compile are skipped automatically (cached failure markers); they are retried when the source or compiler flags change.
|
|
|
|
```bash
|
|
pit build # build all packages
|
|
pit build <package> # build specific package
|
|
pit build /Users/john/work/mylib # build local package
|
|
pit build . # build current directory
|
|
pit build -t macos_arm64 # cross-compile for target
|
|
pit build -b debug # build type: release (default), debug, minsize
|
|
pit build --list-targets # list available targets
|
|
pit build --force # force rebuild
|
|
pit build --dry-run # show what would be built
|
|
pit build --verbose # print resolved flags, commands, cache status
|
|
```
|
|
|
|
### pit test
|
|
|
|
Run tests. See [Testing](/docs/testing/) for the full guide.
|
|
|
|
```bash
|
|
pit test # run tests in current package
|
|
pit test suite # run specific test file
|
|
pit test all # run all tests in current package
|
|
pit test package <name> # run tests in a named package
|
|
pit test package /Users/john/work/mylib # run tests for a local package
|
|
pit test package all # run tests from all packages
|
|
pit test suite --verify --diff # with IR verification and differential testing
|
|
```
|
|
|
|
### pit ls
|
|
|
|
List modules and actors in a package.
|
|
|
|
```bash
|
|
pit ls # list files in current project
|
|
pit ls <package> # list files in specified package
|
|
```
|
|
|
|
### pit audit
|
|
|
|
Test-compile all `.ce` and `.cm` scripts in package(s). Continues past failures and reports all errors at the end.
|
|
|
|
```bash
|
|
pit audit # audit all installed packages
|
|
pit audit <package> # audit specific package
|
|
pit audit . # audit current directory
|
|
```
|
|
|
|
### pit resolve
|
|
|
|
Print the fully resolved dependency closure for a package.
|
|
|
|
```bash
|
|
pit resolve # resolve current package
|
|
pit resolve <package> # resolve specific package
|
|
pit resolve --locked # show lock state without links
|
|
```
|
|
|
|
### pit graph
|
|
|
|
Emit a dependency graph.
|
|
|
|
```bash
|
|
pit graph # tree of current package
|
|
pit graph --format dot # graphviz dot output
|
|
pit graph --format json # json output
|
|
pit graph --world # graph all installed packages
|
|
pit graph --locked # show lock view without links
|
|
```
|
|
|
|
### pit verify
|
|
|
|
Verify integrity and consistency of packages, links, and builds.
|
|
|
|
```bash
|
|
pit verify # verify current package
|
|
pit verify shop # verify entire shop
|
|
pit verify --deep # traverse full dependency closure
|
|
pit verify --target <triple>
|
|
```
|
|
|
|
### pit pack
|
|
|
|
Build a statically linked binary from a package and all its dependencies.
|
|
|
|
```bash
|
|
pit pack <package> # build static binary (output: app)
|
|
pit pack <package> -o myapp # specify output name
|
|
pit pack <package> -t <triple> # cross-compile for target
|
|
```
|
|
|
|
### pit config
|
|
|
|
Manage system and actor configuration values in `cell.toml`.
|
|
|
|
```bash
|
|
pit config list # list all config
|
|
pit config get system.ar_timer # get a value
|
|
pit config set system.ar_timer 5.0 # set a value
|
|
pit config actor <name> list # list actor config
|
|
pit config actor <name> get <key> # get actor config
|
|
pit config actor <name> set <key> <val> # set actor config
|
|
```
|
|
|
|
### pit bench
|
|
|
|
Run benchmarks with statistical analysis. Benchmark files are `.cm` modules in a package's `benches/` directory.
|
|
|
|
```bash
|
|
pit bench # run all benchmarks in current package
|
|
pit bench all # same as above
|
|
pit bench <suite> # run specific benchmark file
|
|
pit bench package <name> # benchmark a named package
|
|
pit bench package <name> <suite> # specific benchmark in a package
|
|
pit bench package all # benchmark all packages
|
|
pit bench --bytecode <suite> # force bytecode-only benchmark run
|
|
pit bench --native <suite> # force native-only benchmark run
|
|
pit bench --compare <suite> # run bytecode and native side-by-side
|
|
```
|
|
|
|
Output includes median, mean, standard deviation, and percentiles for each benchmark.
|
|
|
|
## Shop Commands
|
|
|
|
These commands operate on the global shop (`~/.cell/`) or system-level state.
|
|
|
|
### pit install
|
|
|
|
Install a package to the shop.
|
|
|
|
```bash
|
|
pit install gitea.pockle.world/john/prosperon
|
|
pit install /Users/john/local/mypackage # local path
|
|
```
|
|
|
|
### pit remove
|
|
|
|
Remove a package from the shop. Removes the lock entry, the package directory (or symlink), and any built dylibs.
|
|
|
|
```bash
|
|
pit remove gitea.pockle.world/john/oldpackage
|
|
pit remove /Users/john/work/mylib # local path
|
|
pit remove . # current directory
|
|
pit remove mypackage --dry-run # show what would be removed
|
|
pit remove mypackage --prune # also remove orphaned dependencies
|
|
```
|
|
|
|
Options:
|
|
- `--prune` — also remove packages that are no longer needed by any remaining root
|
|
- `--dry-run` — show what would be removed without removing anything
|
|
|
|
### pit update
|
|
|
|
Update packages from remote sources.
|
|
|
|
```bash
|
|
pit update # update all packages
|
|
pit update <package> # update specific package
|
|
```
|
|
|
|
### pit list
|
|
|
|
List installed packages.
|
|
|
|
```bash
|
|
pit list # list all installed packages
|
|
pit list <package> # list dependencies of a package
|
|
```
|
|
|
|
### pit link
|
|
|
|
Manage local package links for development.
|
|
|
|
```bash
|
|
pit link add <canonical> <local_path> # link a package
|
|
pit link list # show all links
|
|
pit link delete <canonical> # remove a link
|
|
pit link clear # remove all links
|
|
```
|
|
|
|
### pit unlink
|
|
|
|
Remove a link created by `pit link` or `pit clone` and restore the original package.
|
|
|
|
```bash
|
|
pit unlink gitea.pockle.world/john/prosperon
|
|
```
|
|
|
|
### pit clone
|
|
|
|
Clone a package to a local path and link it for development.
|
|
|
|
```bash
|
|
pit clone gitea.pockle.world/john/prosperon ./prosperon
|
|
```
|
|
|
|
### pit fetch
|
|
|
|
Fetch package sources without extracting.
|
|
|
|
```bash
|
|
pit fetch <package>
|
|
```
|
|
|
|
### pit search
|
|
|
|
Search for packages, actors, or modules matching a query.
|
|
|
|
```bash
|
|
pit search math
|
|
```
|
|
|
|
### pit why
|
|
|
|
Show which installed packages depend on a given package (reverse dependency lookup).
|
|
|
|
```bash
|
|
pit why gitea.pockle.world/john/prosperon
|
|
```
|
|
|
|
### pit upgrade
|
|
|
|
Upgrade the ƿit installation itself.
|
|
|
|
```bash
|
|
pit upgrade
|
|
```
|
|
|
|
### pit clean
|
|
|
|
Clean build artifacts.
|
|
|
|
```bash
|
|
pit clean
|
|
```
|
|
|
|
## Logging
|
|
|
|
### pit log
|
|
|
|
Manage log sinks and read log files. See [Logging](/docs/logging/) for the full guide.
|
|
|
|
### pit log list
|
|
|
|
List configured sinks.
|
|
|
|
```bash
|
|
pit log list
|
|
```
|
|
|
|
### pit log add
|
|
|
|
Add a log sink.
|
|
|
|
```bash
|
|
pit log add <name> console [options] # add a console sink
|
|
pit log add <name> file <path> [options] # add a file sink
|
|
```
|
|
|
|
Options:
|
|
|
|
- `--format=pretty|bare|json` — output format (default: `pretty` for console, `json` for file)
|
|
- `--channels=ch1,ch2` — channels to subscribe (default: `console,error,system`). Use `'*'` for all channels (quote to prevent shell glob expansion).
|
|
- `--exclude=ch1,ch2` — channels to exclude (useful with `'*'`)
|
|
- `--stack=ch1,ch2` — channels that capture a full stack trace (default: `error`)
|
|
|
|
```bash
|
|
pit log add terminal console --format=bare --channels=console
|
|
pit log add errors file .cell/logs/errors.jsonl --channels=error
|
|
pit log add dump file .cell/logs/dump.jsonl '--channels=*' --exclude=console
|
|
pit log add debug console --channels=error,debug --stack=error,debug
|
|
```
|
|
|
|
### pit log remove
|
|
|
|
Remove a sink.
|
|
|
|
```bash
|
|
pit log remove <name>
|
|
```
|
|
|
|
### pit log read
|
|
|
|
Read entries from a file sink.
|
|
|
|
```bash
|
|
pit log read <sink> [options]
|
|
```
|
|
|
|
Options:
|
|
|
|
- `--lines=N` — show last N entries
|
|
- `--channel=X` — filter by channel
|
|
- `--since=timestamp` — only show entries after timestamp (seconds since epoch)
|
|
|
|
```bash
|
|
pit log read errors --lines=50
|
|
pit log read dump --channel=debug --lines=10
|
|
pit log read errors --since=1702656000
|
|
```
|
|
|
|
### pit log tail
|
|
|
|
Follow a file sink in real time.
|
|
|
|
```bash
|
|
pit log tail <sink> [--lines=N]
|
|
```
|
|
|
|
`--lines=N` controls how many existing entries to show on start (default: 10).
|
|
|
|
```bash
|
|
pit log tail dump
|
|
pit log tail errors --lines=20
|
|
```
|
|
|
|
## Developer Commands
|
|
|
|
Compiler pipeline tools, analysis, and testing. These are primarily useful for developing the ƿit compiler and runtime.
|
|
|
|
### Compiler Pipeline
|
|
|
|
Each of these commands runs the compilation pipeline up to a specific stage and prints the intermediate output. They take a source file as input.
|
|
|
|
### pit tokenize
|
|
|
|
Tokenize a source file and output the token stream as JSON.
|
|
|
|
```bash
|
|
pit tokenize <file.cm>
|
|
```
|
|
|
|
### pit parse
|
|
|
|
Parse a source file and output the AST as JSON.
|
|
|
|
```bash
|
|
pit parse <file.cm>
|
|
```
|
|
|
|
### pit fold
|
|
|
|
Run constant folding and semantic analysis on a source file and output the simplified AST as JSON.
|
|
|
|
```bash
|
|
pit fold <file.cm>
|
|
```
|
|
|
|
### pit mcode
|
|
|
|
Compile a source file to mcode (machine-independent intermediate representation) and output as JSON.
|
|
|
|
```bash
|
|
pit mcode <file.cm>
|
|
```
|
|
|
|
### pit streamline
|
|
|
|
Apply the full optimization pipeline to a source file and output optimized mcode as JSON.
|
|
|
|
```bash
|
|
pit streamline <file.cm> # full optimized IR as JSON (default)
|
|
pit streamline --stats <file.cm> # summary stats per function
|
|
pit streamline --ir <file.cm> # human-readable IR
|
|
pit streamline --check <file.cm> # warnings only (e.g. high slot count)
|
|
```
|
|
|
|
Flags can be combined. `--stats` output includes function name, args, slots, instruction counts by category, and nops eliminated. `--check` warns when `nr_slots > 200` (approaching the 255 limit).
|
|
|
|
### pit qbe
|
|
|
|
Compile a source file to QBE intermediate language (for native code generation).
|
|
|
|
```bash
|
|
pit qbe <file.cm>
|
|
```
|
|
|
|
### pit compile
|
|
|
|
Compile a source file to a native dynamic library.
|
|
|
|
```bash
|
|
pit compile <file.cm> # outputs .dylib to ~/.cell/build/
|
|
pit compile <file.ce>
|
|
```
|
|
|
|
### pit run_native
|
|
|
|
Compile a module natively and compare execution against interpreted mode, showing timing differences.
|
|
|
|
```bash
|
|
pit run_native <module> # compare interpreted vs native
|
|
pit run_native <module> <test_arg> # pass argument to module function
|
|
```
|
|
|
|
### pit run_aot
|
|
|
|
Ahead-of-time compile and execute a program natively.
|
|
|
|
```bash
|
|
pit run_aot <program.ce>
|
|
```
|
|
|
|
### pit seed
|
|
|
|
Regenerate the boot seed files in `boot/`. Seeds are pre-compiled mcode IR (JSON) that bootstrap the compilation pipeline on cold start. They only need regenerating when the pipeline source changes in a way the existing seeds can't compile, or before distribution.
|
|
|
|
```bash
|
|
pit seed # regenerate all boot seeds
|
|
pit seed --clean # also clear the build cache after
|
|
```
|
|
|
|
The engine recompiles pipeline modules automatically when source changes (via content-addressed cache). Seeds are a fallback for cold start when no cache exists.
|
|
|
|
### Analysis
|
|
|
|
### pit explain
|
|
|
|
Query the semantic index for symbol information at a specific source location or by name.
|
|
|
|
```bash
|
|
pit explain --span <file:line:col> # find symbol at position
|
|
pit explain --symbol <name> [files...] # find symbol by name
|
|
pit explain --help # show usage
|
|
```
|
|
|
|
### pit index
|
|
|
|
Build a semantic index for a source file and output symbol information as JSON.
|
|
|
|
```bash
|
|
pit index <file.cm> # output to stdout
|
|
pit index <file.cm> -o index.json # output to file
|
|
pit index --help # show usage
|
|
```
|
|
|
|
### pit ir_report
|
|
|
|
Optimizer flight recorder — capture detailed information about IR transformations during optimization.
|
|
|
|
```bash
|
|
pit ir_report <file.cm> # per-pass JSON summaries (default)
|
|
pit ir_report <file.cm> --events # include rewrite events
|
|
pit ir_report <file.cm> --types # include type deltas
|
|
pit ir_report <file.cm> --ir-before=PASS # print IR before specific pass
|
|
pit ir_report <file.cm> --ir-after=PASS # print IR after specific pass
|
|
pit ir_report <file.cm> --ir-all # print IR before/after every pass
|
|
pit ir_report <file.cm> --full # all options combined
|
|
```
|
|
|
|
Output is NDJSON (newline-delimited JSON).
|
|
|
|
### Testing
|
|
|
|
### pit diff
|
|
|
|
Differential testing — run tests with and without optimizations and compare results.
|
|
|
|
```bash
|
|
pit diff # diff all test files in current package
|
|
pit diff <suite> # diff specific test file
|
|
pit diff tests/<path> # diff by path
|
|
```
|
|
|
|
### pit fuzz
|
|
|
|
Random program fuzzer — generates random programs and checks for optimization correctness by comparing optimized vs unoptimized execution.
|
|
|
|
```bash
|
|
pit fuzz # 100 iterations with random seed
|
|
pit fuzz <iterations> # specific number of iterations
|
|
pit fuzz --seed <N> # start at specific seed
|
|
pit fuzz <iterations> --seed <N>
|
|
```
|
|
|
|
Failures are saved to `tests/fuzz_failures/`.
|
|
|
|
### pit vm_suite
|
|
|
|
Run the VM stability test suite (641 tests covering arithmetic, strings, control flow, closures, objects, and more).
|
|
|
|
```bash
|
|
pit vm_suite
|
|
```
|
|
|
|
### pit syntax_suite
|
|
|
|
Run the syntax feature test suite (covers all literal types, operators, control flow, functions, prototypes, and more).
|
|
|
|
```bash
|
|
pit syntax_suite
|
|
```
|
|
|
|
## Package Locators
|
|
|
|
Packages are identified by locators:
|
|
|
|
- **Remote**: `gitea.pockle.world/user/repo`
|
|
- **Local**: `/absolute/path/to/package`
|
|
|
|
```bash
|
|
pit install gitea.pockle.world/john/prosperon
|
|
pit install /Users/john/work/mylib
|
|
```
|
|
|
|
## Configuration
|
|
|
|
ƿit stores its data in `~/.cell/`:
|
|
|
|
```
|
|
~/.cell/
|
|
├── packages/ # installed package sources
|
|
├── build/ # content-addressed cache (bytecode, dylibs, manifests)
|
|
├── cache/ # downloaded archives
|
|
├── lock.toml # installed package versions
|
|
└── link.toml # local development links
|
|
```
|
|
|
|
## Environment
|
|
|
|
ƿit reads the `HOME` environment variable to locate the shop directory.
|
|
|
|
## Exit Codes
|
|
|
|
- `0` — Success
|
|
- Non-zero — Error (check output for details)
|