cell/docs/cli.md

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

```bash
pit remove gitea.pockle.world/john/oldpackage
```

### 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 the current package. Compiles C files into per-file dynamic libraries and installs them to `~/.pit/lib/<pkg>/<stem>.dylib`.

```bash
pit build              # build current package
pit build <package>    # build specific package
```

### pit test

Run tests. See [Testing](/docs/testing/) for the full guide.

```bash
pit test            # run tests in current package
pit test all        # run all tests
pit test <package>  # run tests in specific package
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. Updates `cell.toml` and installs the package to the shop.

```bash
pit add gitea.pockle.world/john/prosperon         # default alias
pit add gitea.pockle.world/john/prosperon myalias  # custom alias
```

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