301 lines
7.5 KiB
Markdown
301 lines
7.5 KiB
Markdown
---
|
|
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]
|
|
```
|
|
|
|
## 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 <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.
|
|
|
|
```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 <package> # list dependencies of a package
|
|
```
|
|
|
|
### 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 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 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 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 fetch
|
|
|
|
Fetch package sources without extracting.
|
|
|
|
```bash
|
|
pit fetch <package>
|
|
```
|
|
|
|
### 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 <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 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 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 help
|
|
|
|
Display help information.
|
|
|
|
```bash
|
|
pit help
|
|
pit help <command>
|
|
```
|
|
|
|
## 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)
|