cell/docs/cli.md

title, description, weight, type

title	description	weight	type
Command Line Interface	The pit tool	40	docs

ƿit provides a command-line interface for managing packages, running scripts, and building applications.

Basic Usage

pit <command> [arguments]

General

pit version

Display the ƿit version.

pit version
# 0.1.0

pit help

Display help information.

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.

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.

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 for the full guide.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

pit update              # update all packages
pit update <package>    # update specific package

pit list

List installed packages.

pit list              # list all installed packages
pit list <package>    # list dependencies of a package

pit link

Manage local package links for development.

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.

pit unlink gitea.pockle.world/john/prosperon

pit clone

Clone a package to a local path and link it for development.

pit clone gitea.pockle.world/john/prosperon ./prosperon

pit fetch

Fetch package sources without extracting.

pit fetch <package>

pit search

Search for packages, actors, or modules matching a query.

pit search math

pit why

Show which installed packages depend on a given package (reverse dependency lookup).

pit why gitea.pockle.world/john/prosperon

pit upgrade

Upgrade the ƿit installation itself.

pit upgrade

pit clean

Clean build artifacts.

pit clean

Logging

pit log

Manage log sinks and read log files. See Logging for the full guide.

pit log list

List configured sinks.

pit log list

pit log add

Add a log sink.

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)

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.

pit log remove <name>

pit log read

Read entries from a file sink.

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)

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.

pit log tail <sink> [--lines=N]

--lines=N controls how many existing entries to show on start (default: 10).

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.

pit tokenize <file.cm>

pit parse

Parse a source file and output the AST as JSON.

pit parse <file.cm>

pit fold

Run constant folding and semantic analysis on a source file and output the simplified AST as JSON.

pit fold <file.cm>

pit mcode

Compile a source file to mcode (machine-independent intermediate representation) and output as JSON.

pit mcode <file.cm>

pit streamline

Apply the full optimization pipeline to a source file and output optimized mcode as JSON.

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).

pit qbe <file.cm>

pit compile

Compile a source file to a native dynamic library.

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.

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.

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.

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.

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.

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.

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.

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.

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).

pit vm_suite

pit syntax_suite

Run the syntax feature test suite (covers all literal types, operators, control flow, functions, prototypes, and more).

pit syntax_suite

Package Locators

Packages are identified by locators:

• Remote: gitea.pockle.world/user/repo
• Local: /absolute/path/to/package

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)