--- 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 [arguments] ``` ## General ### pit version Display the ƿit version. ```bash pit version # 0.1.0 ``` ### pit help Display help information. ```bash pit help pit help ``` ## 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 and installs them to `~/.pit/lib//.dylib`. C files in `src/` directories are compiled as support objects and linked into the module dylibs. ```bash pit build # build all packages pit build # 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 # 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 # 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 # 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 # 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 ``` ### pit pack Build a statically linked binary from a package and all its dependencies. ```bash pit pack # build static binary (output: app) pit pack -o myapp # specify output name pit pack -t # 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 list # list actor config pit config actor get # get actor config pit config actor set # 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 # run specific benchmark file pit bench package # benchmark a named package pit bench package # specific benchmark in a package pit bench package all # benchmark all packages ``` Output includes median, mean, standard deviation, and percentiles for each benchmark. ## Shop Commands These commands operate on the global shop (`~/.pit/`) 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 # update specific package ``` ### pit list List installed packages. ```bash pit list # list all installed packages pit list # list dependencies of a package ``` ### pit link Manage local package links for development. ```bash pit link add # link a package pit link list # show all links pit link delete # 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 ``` ### 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 ``` ## 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 ``` ### pit parse Parse a source file and output the AST as JSON. ```bash pit parse ``` ### pit fold Run constant folding and semantic analysis on a source file and output the simplified AST as JSON. ```bash pit fold ``` ### pit mcode Compile a source file to mcode (machine-independent intermediate representation) and output as JSON. ```bash pit mcode ``` ### pit streamline Apply the full optimization pipeline to a source file and output optimized mcode as JSON. ```bash pit streamline # full optimized IR as JSON (default) pit streamline --stats # summary stats per function pit streamline --ir # human-readable IR pit streamline --check # 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 ``` ### pit compile Compile a source file to a native dynamic library. ```bash pit compile # outputs .dylib to .cell/lib/ pit compile ``` ### pit run_native Compile a module natively and compare execution against interpreted mode, showing timing differences. ```bash pit run_native # compare interpreted vs native pit run_native # pass argument to module function ``` ### pit run_aot Ahead-of-time compile and execute a program natively. ```bash pit run_aot ``` ### 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 # find symbol at position pit explain --symbol [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 # output to stdout pit index -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 # per-pass JSON summaries (default) pit ir_report --events # include rewrite events pit ir_report --types # include type deltas pit ir_report --ir-before=PASS # print IR before specific pass pit ir_report --ir-after=PASS # print IR after specific pass pit ir_report --ir-all # print IR before/after every pass pit ir_report --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 # diff specific test file pit diff tests/ # 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 # specific number of iterations pit fuzz --seed # start at specific seed pit fuzz --seed ``` 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 `~/.pit/`: ``` ~/.pit/ ├── packages/ # installed package sources ├── lib/ # installed per-file dylibs and mach (persistent) │ ├── core/ # core package: .dylib and .mach files │ └── / # per-package subdirectories ├── build/ # ephemeral build cache (safe to delete) ├── 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)