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, serve and derive --follow prints one JSON envelope on stdout: mcp speaks MCP there, serve git's protocol, and derive --follow prints one envelope a line for each run that derived something. An envelope's 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.
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.
swarmops init: Create a store in DIR, and describe it.swarmops 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 upgrade: Move the store to the latest format this build writes. Irreversible: older releases do not open it afterwards.swarmops derive: Derive the eager derived values of new changesets, ahead of any reader.
swarmops commit: Record a changeset from a list of changes; with --advance, also move that ref to it.swarmops land: Merge a change three-way onto a ref and publish it there as one new changeset.swarmops rebase: Merge a change three-way onto a ref's head and record the result there as one changeset, moving no ref.
Store content as a blob for a commit to name by its id, or ask which blobs the store holds.
swarmops 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: Of the IDs given, list those the store holds blobs under.
swarmops resolve: Name the changeset REV names, and whether REV is a ref's name.swarmops cat: Print one file at a revision, or part of it: from a byte, or a range of lines.swarmops ls: List one directory at a revision (the root without a PATH), and with --depth the directories below it.swarmops show: Show one changeset.swarmops log: List history along first parents, newest first.swarmops history: List the changesets that changed a path, newest first, along first parents.swarmops diff: List the files that differ between two revisions, a page at a time.
Store content as a blob for a commit to name by its id, or ask which blobs the store holds.
swarmops blob get: Print the blobs the IDs name, each with its size and content as cat gives a file's.
List refs, or move one by compare-and-swap.
swarmops ref list: List every ref, or those whose names start with --prefix, each with its kind.swarmops ref set: Point ref NAME at REV: move it from --expect, or --create it.swarmops ref delete: Delete ref NAME.
List the store's operations, or undo one.
swarmops op log: List the store's operations, newest first: each write transaction, its changesets and its ref moves.swarmops op undo: Move every ref operation OP moved back to what it named before, all or none.
swarmops verify: Check the store's consistency.swarmops gc: Remove the store's leftovers: temp files past a day, a crashed create's staging, derived values of older versions, what an upgrade left. Never an object or a changeset.swarmops repair: Rebuild what the journal can rebuild, quarantine damaged objects, drop damaged cache entries, then verify; the journal itself is never cut.
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.
swarmops clone: Make a store from a git remote: fetch it, import its default branch into main, and record it as a remote.swarmops fetch: Fetch a git remote into the store's mirror, and its followed branch into the store.swarmops push: Send a store ref to a git remote's branch by compare-and-swap, never by force.swarmops sync: Land main's unpublished changes onto a git remote's head, and push them.
Add, remove or list the store's git remotes.
swarmops remote add: Record a git remote in the store.swarmops remote remove: Forget a git remote, and the mirror's refs of it; no changeset is removed.swarmops remote list: List the store's git remotes.
Land main's unpublished changes onto a git remote's head, and push them.
swarmops sync: Land main's unpublished changes onto a git remote's head, and push them.swarmops sync status: Show how main and a git remote's followed branch stand, as the last fetch saw it.
Work in a directory of your own: a workspace holds a sparse copy of a changeset's tree.
swarmops ws create: Make a workspace NAME in a directory of its own, and bootstrap it.swarmops ws status: What changed in a workspace against its head, and how far its target has moved.swarmops ws diff: A workspace's edits against its head, as diff gives a diff.swarmops ws commit: Record a workspace's edits as one changeset on its head.swarmops ws rebase: Move a workspace's chain onto its target's head, and its files with it.swarmops ws resolve: Mark conflicting paths of a rebase resolved.swarmops ws land: Land a workspace's chain on its target; with --check, rebase, check and land the checked tree.swarmops ws materialize: Write out more of a workspace's tree: the paths join its prefixes.swarmops ws discard: Restore paths of a workspace from its head, every changed one without a PATH: the edits are lost.swarmops ws list: List the store's workspaces.swarmops ws info: Describe one workspace: its directory, base, head and prefixes.swarmops ws delete: Remove a workspace's directory, then its entry.swarmops ws hook: The Claude Code hooks: read the hook's JSON on stdin, print what the hook expects.
swarmops mcp: Serve the store's operations to an agent as an MCP server on stdin and stdout.swarmops serve: Serve the stores under --root to stock git: fetch, clone and push over ssh as a forced command, or over smart HTTP as a CGI program.