CLI reference#
Every command of swarmops and so, its short form: the same program by a shorter name. This page and the command pages are generated from the command line's own definition, so they say what swarmops <command> --help says. -h prints the short help and --help the long help that the pages give.
Every command but mcp prints one JSON envelope on stdout; its op names the operation the command runs (cat runs read_file). Errors lists every error code an envelope can carry, with its exit code.
Each command's page gives its syntax, its arguments, an example recorded by the tests, what it returns and the errors it fails with. Its yaml metadata block says the same for programs: group, mutates (it can change what the store holds, its changesets and refs, or make the store; a write to the store's caches alone does not count), identity_required (it refuses to run without --as or SWARMOPS_AGENT), mcp_tool, envelope_op, exit_codes, errors and syntax.
Global options#
Every command takes these, before or after its subcommand.
| Option | Required | Description | Default |
|---|---|---|---|
--repo <STORE> | no | The store to use (default: $SWARMOPS_REPO). | |
--as <AGENT> | no | The agent to act as, <family>/<instance> (default: $SWARMOPS_AGENT). | |
--json | no | Print the JSON envelope: the default, unless $SWARMOPS_FORMAT is human. | |
--human | no | Print a short text rendering instead of JSON. | |
--pretty[=<BOOL>] | no | Pretty-print the JSON (default: when stdout is a terminal). |
-h prints a command's short help and --help its long help, as plain text, not an envelope. swarmops --version prints the version.
Commands#
| Command | MCP tool | Summary |
|---|---|---|
| Store | ||
swarmops init | Create a store in DIR, and describe it. | |
swarmops info | repo_info | Describe the store. |
swarmops whoami | Show the identity this caller's changes carry. | |
swarmops schema | Print the JSON Schema of every request and response type, or of TYPE's. | |
swarmops derive | Derive the eager derived values of new changesets, ahead of any reader. | |
| Write | ||
swarmops commit | commit | Record a changeset from a list of changes; with --advance, also move that ref to it. |
swarmops land | land | Merge a change three-way onto a ref and publish it there as one new changeset. |
swarmops blob | Store content as a blob for a commit to name by its id, or ask which blobs the store holds. | |
swarmops blob put | blob_put | Store FILE's content as a blob, outside any commit, and print its id, which a change names it by: {"blob": ID}. A change list holds at most 64 MiB and a commit's contents 1 GiB together; a blob named by id counts toward neither. |
swarmops blob has | blob_has | Of the IDs given, list those the store holds blobs under. |
| Read | ||
swarmops resolve | resolve_rev | Name the changeset REV names, and whether REV is a ref's name. |
swarmops cat | read_file | Print one file at a revision, or part of it: from a byte, or a range of lines. |
swarmops ls | read_tree | List one directory at a revision (the root without a PATH), and with --depth the directories below it. |
swarmops show | show | Show one changeset. |
swarmops log | log | List history along first parents, newest first. |
swarmops history | path_history | List the changesets that changed a path, newest first, along first parents. |
swarmops diff | diff | List the files that differ between two revisions, a page at a time. |
| Refs | ||
swarmops ref | List refs, or move one by compare-and-swap. | |
swarmops ref list | ref_list | List every ref. |
swarmops ref set | ref_set | Point ref NAME at REV: move it from --expect, or --create it. |
swarmops ref delete | ref_delete | Delete ref NAME. |
| Operations | ||
swarmops op | List the store's operations, or undo one. | |
swarmops op log | op_log | List the store's operations, newest first: each write transaction, its changesets and its ref moves. |
swarmops op undo | undo | Move every ref operation OP moved back to what it named before, all or none. |
| Integrity | ||
swarmops verify | verify | Check the store's consistency. |
| Git | ||
swarmops git | Bring history in from git, or send it back. | |
swarmops git import | Bring a git repository's history in: every commit --ref reaches that the store does not hold, then move --into to it. | |
swarmops git export | Send the store's history to git: write every commit of --ref's history that --branch's last export does not reach into the git repository at PATH, then move --branch to it. | |
| Server | ||
swarmops mcp | Serve the store's operations to an agent as an MCP server on stdin and stdout. | |