CLI reference

The CLI has three faces: Rig (the package — author & distribute), Workspace (a live, synced instance — share & collaborate), and Hub (distribution). The tapd engine is internal; rig is the only surface you call.

Global flags

Flag	What
`--version`, `-v`	Print the CLI version.
`--help`, `-h`	Print help. Combine with a command for command-specific help.
`--plain`	Suppress prompts/spinners. Auto-on when stdin/stdout aren't TTY.
`--json`	One-line `{ "protocolVersion": 1, ... }` (or `{ ..., "error": { "code", "message" } }` on failure). Implies `--plain`.

Rig — the package

`rig init`

Initialise a rig by inspecting the current directory.

rig init [--no-sync] [--force] [--author <name>] [--plain] [--json]

Flag	What
`--no-sync`	Write `[sync] enabled = false` (local-only). Default is `enabled = true` (sync-capable; see the sync block).
`--force`	Overwrite an existing `rig.toml`.
`--author <name>`	Set `[rig].author` without prompting.

Writes rig.toml (incl. [sync]), .claude/skills/rig/SKILL.md, .claude/CLAUDE.md. Details: Initialize a rig.

`rig add <file-or-glob> [...]`

Add a file or glob to [package].include. Details: Add files.

`rig pack`

rig pack [--out <dir>] [--preview] [--plain] [--json]

Package the rig into a .rig.tgz. --preview prints what would be packaged without writing. Details: Package.

`rig inspect <source>`

Show artifact metadata + manifest + file list. Details: Inspect.

`rig install` (alias: `rig setup`)

Run setup for the current rig — create dirs, collect env, merge permissions.

rig install [--yes] [--interactive] [--run-hooks] [--env KEY=value]... [--env-file <path>] [--plain] [--json]

Details: Run setup.

`rig doctor`

rig doctor [--json] [--plain]

Walk the workspace, run every declared check, emit a readiness report. Exit 0 if all required checks pass. Details: Troubleshoot, Doctor JSON.

Workspace — live & shared

A rig becomes a live workspace the first time you share or join it (it auto-enables [sync] and announces it). These verbs operate on the current rig's binding. (Legacy: each maps from an old rig collab … subcommand — see Collaborate.)

rig share                                            # read-only: print current access
rig share --enable                                   # go live without inviting
rig share <email> [--role editor|viewer] [--expires <dur>] [--new] [--json]
rig share --ops <read,write,subscribe> [--path <glob>]... [--expires <dur>] [--max-uses <n>] [--label <s>] [--json]

Form	What
(no args)	Read-only listing (alias of `rig who`). Does not bind.
`--enable`	Bind + go live without inviting anyone.
`<email>`	Invite a person. Binds + announces if needed. `--new` rotates an existing pending invite (the secret URL is shown once; a duplicate returns `alreadyExisted: true, url: null`).
`--ops …`	Scoped / agent access — pure capability, role-less (`--role` and `--ops` are mutually exclusive).

--json → { protocolVersion, enabledSync, workspace: { bindingId, homeUrl }, invite: { id, role, email, ops, paths, url, expiresAt, alreadyExisted } }.

`rig who`

rig who [--json]

Read-only: members (name, role), pending invites, scoped tokens. (Devices are coming.)

`rig unshare <target>`

rig unshare <inv_… | dev_… | userId | email | label> [--json]

Revoke a grant — member, invite, or scoped token; cascade-revokes its device tokens. An ambiguous email/label returns error.code = "ambiguous_target" with candidates.

`rig role <member> <editor|viewer>`

rig role <email|userId> <editor|viewer> [--json]

Change a member's role. owner is rejected (owner_transfer_unsupported).

`rig join <invite-url>`

rig join <invite-url> [--anonymous] [--device-label <s>] [--plain] [--json]

Join someone else's workspace. --anonymous accepts a pure-capability (role-less) invite without an account. Self-authorizing — not blocked by a local [sync] opt-out. Details: Join.

`rig status`

rig status [--verbose] [--json]

`rig disconnect`

rig disconnect [--purge] [--plain] [--json]

Local checkout only — drop the binding pointer + stop this device's daemon (remote workspace, your membership, and collaborators untouched). --purge also removes manifest-tracked files. Details: Leave.

`rig pause` / `rig resume`

Halt / restore this device's sync daemon. Details: Daemon.

`rig history <path>` / `rig restore <path>`

rig history <path> [--limit <n>] [--json]
rig restore <path> [--as-of <cursor>] [--yes] [--json]

List a file's change events / restore it from the relay log. Details: Recovery.

`rig mount` / `rig mounts` / `rig unmount`

rig mount <invite-url> --path <subdir> [--json]   # read-only meta-rig mount
rig mounts [--json]
rig unmount <name|path> [--json]

Mount another rig read-only into a subdir. Runs the sync engine for that binding; does not bind the current rig.

Hub — distribution

`rig hub publish`

rig hub publish [<artifact>] [--force] [--no-wait] [--allow-conflicts] [--json]
rig hub publish --registry <dir> [<artifact>]

Snapshot the rig to the Hub (--registry <dir> for a local registry instead). Requires rig login. On a live workspace it waits for sync to settle; pending uploads → --no-wait/--force, unresolved conflicts → --allow-conflicts. Details: Publish.

`rig hub use <source>`

rig hub use <source> [--dir <path>] [--force] [--plain] [--json]

Install a rig from a source (hub:, github:, ./path.rig.tgz, registry: — see Sources). Details: Install a rig.

`rig hub update`

rig hub update [<source>] [--check] [--interactive | --yes] [--plain] [--json]

Update an installed rig to a newer version (from .rig/instance.toml). Refuses on unclean sync. Alias: rig update. Details: Update.

`rig hub search <query>` / `rig hub list [<registry>]`

rig hub search <query> [--json] [--plain]
rig hub list [<registry>]

Search the Hub / list a local registry. Details: Find a rig, Local registry.

Account

Hub authentication via device-flow OAuth; token at ~/.config/rig/config.json. Details: Accounts.

Legacy aliases

rig collab <sub>, rig publish, rig use, rig search, rig list, rig import/imports still work and print a one-line nudge to the new verb.