# CLI Lookup for `rig` commands. First session is on Getting started. Webhook HTTP is in https://rig.slopkit.dev/raw/triggers.md. A workspace is a flake that calls `rig.lib.workspace`. `rig new workspace` writes one. Build, catalog lists, and `rig add` need it. Pulled images do not. `RIG_ROOT` can point at one. This page matches slopkit/rig VERSION 0.4.36 for the commands that page installed. `rig update` re-runs the installer. `rig help` prints the full usage. `rig --help` prints one command. ## rig pull Download a published agent or layer into the local dest store. ``` rig pull ``` `image|ref` is one of: - `https://host/agents/name@tag` or `https://host/layers/name@tag` - `s3://bucket[/prefix]/agents/name@tag` - `host/name:tag` - `name@tag`, which walks `https://repo.slopkit.dev` then `repositories` in user config Needs no workspace. Progress lines go to stderr when stderr is not a TTY as `rig: …`. The last stdout line is: ``` pulled https://repo.slopkit.dev/agents/agency-tester@latest storePath=/nix/store/…-kit-agent-agency-tester-root cache=https://repo.slopkit.dev/cache ``` A layer with no session root prints `pulled … (no session root) cache=…`. Missing argument exits 1 with `error: pull requires an image or layer ref`. ## rig new Create an empty workspace, or scaffold a layer or agent module. ``` rig new workspace [directory] rig new layer rig new agent ``` `rig new workspace` writes `flake.nix` that calls `rig.lib.workspace`. Default directory is `rig-workspace` in the current directory. ``` created workspace → rig-workspace ``` A destination that exists and is not empty exits 1 with `exists and is not empty`. A destination that starts with `-` exits 1. Creating a layer or agent outside a workspace initializes the current empty directory first. ``` created layer notes → layers/notes created agent writer → agents/writer ``` The layer file is the module body. The agent scaffold lists every local `layers/*/default.nix` name. It does not list flake inputs. Unknown kind exits 1 with `error: usage: rig new workspace [dir] | rig new layer|agent `. ## rig add Pull a published layer and add its flake input to the workspace. Does not edit agent files. Does not add layers named in that layer's own `compose` list. ``` rig add ``` Needs a workspace. Match: ``` added layer git → https://repo.slopkit.dev/layers/git@latest/flake.tar.gz ``` The card must include a flake archive. If it does not, add exits with `layer '' has no flake archive; rig pull still works for run`. Missing argument exits 1 with `error: rig add requires a published layer ref`. ## rig push Publish a local agent or layer to an image repo. ``` rig push [path] ``` `image` is required. `path` is an optional agent or layer directory. If you omit it, Rig searches the current working directory. Needs a workspace or that path, and secretspec credentials for `scopes.s3`. ## rig publish Build NARs and upload to S3. ``` rig publish [--system SYSTEM] rig publish --all [--tag TAG]… [--system SYSTEM] ``` Needs a workspace. `--system` selects a pkgsCross output such as `aarch64-linux`. It does not run a foreign ELF. `--all` publishes every catalog layer, then every agent, once. Extra `--tag` values are written only when that image's store path changed versus `@latest`. Stdout is one line per image: ``` published storePath= cache= uploaded= layers= ``` ## rig agent ``` rig agent list rig agent remove [--force] [--runtime URL] ``` `list` prints pulled agents from `$RIG_DATA_DIR/rigdb.sqlite`. Empty inventory prints `No pulled agents.` A pulled row looks like: ``` Pulled agents: agency-tester latest compose: base flue git unslop agency chromium agent-browser osmani-browser ``` `remove` deletes a pulled agent and unused layer store paths. It refuses if a session uses the image, or if the runtime is down, unless `--force`. ## rig layer ``` rig layer list rig layer remove [--force] [--runtime URL] ``` Same inventory and remove rules for pulled layers. Empty inventory prints `No pulled layers.` ## rig build Materialize a catalog agent to `.agent`. ``` rig build [--harness opencode|claude] [--system SYSTEM] ``` Needs a workspace. That is `nix build .#agents- -o .agent`. Cross is `.#cross..agents-`. `--harness` checks that harness's files exist. It does not build a different derivation. Unknown harness exits 1. Missing name exits 1 with `error: build requires an agent name`. Stdout starts with: ``` build notes: base → notes (flake .#agents-notes) ``` Then a materialized line with `outDir`, `storePath`, and counts for files, skills, and MCP servers. ## rig list-agents List agents from the local flake catalog. Alias: `rig agents`. Needs a workspace. Pulled inventory is `rig agent list`. ``` Agents: compose: ``` ## rig list-layers List layers from the local flake catalog. Alias: `rig layers`. Needs a workspace. Pulled inventory is `rig layer list`. ``` Layers: ``` ## rig inspect ``` rig inspect ``` Print evaluated metadata for a local or pulled layer or agent. A workspace name looks up the catalog. A path such as `./layers/notes` works without a catalog name. An agent block starts with `=== agent: ===` and includes `compose (declared)` and `compose (resolved)`. A layer block starts with `=== layer: ===`. Missing name exits 1 with `error: inspect requires a layer or agent name`. ## rig secrets ``` rig secrets ``` Run `secretspec check` for a catalog agent manifest. Needs a workspace. ## rig card serve ``` rig card serve [--port N] ``` Preview repo, agent, and layer cards from a workspace. Default port is `43191`. Cards are written under `.rig/cards` and served at `127.0.0.1`. ## rig session ``` rig session create --agent [options] rig session list [--runtime URL] rig session get [--runtime URL] rig session suspend [--runtime URL] rig session resume [--runtime URL] ``` `--agent` is a pulled name from `rig agent list`, an image URL, or a local catalog name. Catalog create runs a required-secret check first. Pulled images skip that CLI check. Create starts a local runtime when the target URL is this machine. `--runtime` targets a remote runtime and skips the local start. | Option | Meaning | | --- | --- | | --agent | Required on create. Pulled name, image URL, or catalog name. | | --name | Session name. Default is the image leaf, then `-alpha` through `-zulu`, then `-alpha-alpha`. | | --prompt | Initial prompt. Delivered only when the image wrote `harness.json`. Prompts on one session run one at a time, in order. | | --workdir-host | Bind a host path. The path must exist. Exactly one workdir kind is allowed. | | --workdir-clone | Git URL. Schemes are http, https, ssh, git, git+ssh, file, or `user@host:path`. A URL that starts with `-` is rejected. | | --workdir-ref | Clone ref. Requires `--workdir-clone`. A ref that starts with `-` is rejected. | | --workdir-persistent | Named directory under `$RIG_DATA_DIR/workdirs/`. | | --backend | `nix` or `firecracker`. | | --runtime | Runtime base URL for this command. | If you omit a workdir, the runtime uses a persistent directory named after the session id. Create prints the session name, status, page URL, agent, backend, and id. The URL may include a one-time `login` query. `list` with no sessions prints `(no sessions)`. `get`, `suspend`, and `resume` print JSON. Stopped, failed, or suspended sessions refuse shell. Resume first. On disk the runtime keeps `$RIG_DATA_DIR/sessions//` with `home/`, `workdir/`, `root-path`, and `meta.json`. Inside the root, `$HOME` is `/home/agent` and cwd is `/home/agent/workdir`. ## rig attach ``` rig attach [--runtime URL] ``` Attach stdin and stdout to the session agent process over WSS. Disconnect does not stop the agent. Missing name exits 1. A non-TTY prints attach info as JSON and a hint to run in a TTY. No `harness.json` means the runtime skips the harness process. ## rig shell ``` rig shell [--script 'cmd;…'] [--runtime URL] [--raw-secrets] ``` Bash in the session root. The runtime runs `bwrap`. `--script` splits on `;`, runs those commands, then `exit`, and writes the output to stdout. Timeout for script mode is 15 seconds. `--raw-secrets` skips the secret wrap. A non-TTY without `--script` prints shell info as JSON. ## rig runtime ``` rig runtime start [--port N] [--foreground|-f] rig runtime restart|stop|status rig runtime login [--name ] [--token ] rig runtime switch [name] rig runtime list ``` Start the local runtime, or save and switch remotes. Does not need a workspace. TLS plus token `dev`. Default URL is `https://127.0.0.1:7443`. Start in the background prints `runtime started (background) → ` or that it was already up. `--foreground` keeps it on this terminal. Local listen details land in `~/.config/rig/runtime.json`. `login` saves the URL and makes it current. It needs `--token` or `RIG_RUNTIME_TOKEN`. `--name` labels it. Default name is the URL hostname. Saved remotes land in `~/.config/rig/runtimes.json`. Login prints `rig: runtime → (current)` on stderr. `switch` with no name opens a picker. A named switch prints `rig: current runtime: ()`. `list` marks the current entry with `*`. Empty list prints `(no runtimes)`. `rig supervisor` exits 1 with `unknown command: supervisor`. `--supervisor` exits 1 with `Unknown option '--supervisor'`. ## config.toml User config is `~/.config/rig/config.toml`, or `$XDG_CONFIG_HOME/rig/config.toml`. Override the file with `RIG_USER_CONFIG`. ``` repositories = [ "https://repo.slopkit.dev", "s3://my-rig-cache", ] ``` If the file is missing, or `repositories` is empty, Rig uses `https://repo.slopkit.dev`. Project `rig.toml` is named flake registries only. It does not replace this list. ## Environment | Name | Meaning | | --- | --- | | RIG_USER_CONFIG | Exact path to the user TOML file. | | RIG_CONFIG_DIR | Directory that holds `config.toml`, `runtime.json`, and `runtimes.json`. | | RIG_ROOT | Workspace root for build, inspect, and catalog lists. | | RIG_RUNTIME_URL | Runtime base URL. When unset, the current `runtimes.json` entry, then `runtime.json`, then `https://127.0.0.1:7443`. | | RIG_RUNTIME_TOKEN | Bearer token. Default `dev`. | | RIG_RUNTIME_INSECURE_TLS | `1` or `true` accepts a self-signed cert. `0` or `false` turns that off. Localhost is insecure unless turned off. | | RIG_DATA_DIR | Store, sessions, SQLite. Default `~/.local/share/rig`. | | RIG_BWRAP | bubblewrap binary for session enter. | | RIG_BWRAP_KEEP_ENV | `1` keeps the host environment inside `bwrap`. | | RIG_VERSION | Installer package version. Default `latest`. | Each `RIG_*` name above that has a `KIT_*` twin also reads the `KIT_*` name as a fallback. ## rig version ``` rig version rig --version rig -V ``` Prints three lines: `version:`, `built:`, and `commit:`. Getting started records 0.4.36. ## rig update ``` rig update ``` Downloads and runs the latest `install.sh`. Same installer as Getting started. ## rig config analytics ``` rig config analytics [on|off] ``` Anonymous telemetry is on by default. It records sanitized command, pull, runtime, and session aggregates. It does not record prompts, responses, raw argv, URLs, tokens, paths, or environment variables. Local data is `$XDG_DATA_HOME/rig/analytics.duckdb`, default `~/.local/share/rig/analytics.duckdb`. Dashboard: https://analytics.slopkit.dev.