---
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 and installs them to `~/.pit/lib/<pkg>/<stem>.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 <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
```

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

## 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/lib/
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 `~/.pit/`:

```
~/.pit/
├── packages/       # installed package sources
├── lib/            # installed per-file dylibs and mach (persistent)
│   ├── core/       # core package: .dylib and .mach files
│   └── <pkg>/      # 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)
