--- 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] ``` ## Commands ### pit version Display the ƿit version. ```bash pit version # 0.1.0 ``` ### 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 update Update packages from remote sources. ```bash pit update # update all packages pit update # update specific package ``` ### 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 list List installed packages. ```bash pit list # list all installed packages pit list # list dependencies of a package ``` ### 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 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 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 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 fetch Fetch package sources without extracting. ```bash pit fetch ``` ### pit upgrade Upgrade the ƿit installation itself. ```bash pit upgrade ``` ### pit clean Clean build artifacts. ```bash 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`. ```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 clone Clone a package to a local path and link it for development. ```bash 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. ```bash pit unlink gitea.pockle.world/john/prosperon ``` ### 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 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 help Display help information. ```bash pit help pit help ``` ## 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)