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]

Commands

pit version

Display the ƿit version.

pit version
# 0.1.0

pit install

Install a package to the shop.

pit install gitea.pockle.world/john/prosperon
pit install /Users/john/local/mypackage  # local path

pit update

Update packages from remote sources.

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

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 list

List installed packages.

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

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

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

Fetch package sources without extracting.

pit fetch <package>

pit upgrade

Upgrade the ƿit installation itself.

pit upgrade

pit clean

Clean build artifacts.

pit clean

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 clone

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

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

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

Display help information.

pit help
pit help <command>

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