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