CLI.md

CLI reference

Every command talks to MONGODB_URI (default mongodb://localhost:27017); metadata lives in the argon_wal database. Shared flags: -p/--project, -b/--branch (default main). Commands that advertise -o/--output support table|json; unsupported formats fail before work begins. JSON produces one value on stdout and diagnostics go to stderr. Projects/branches, sandbox, pin, diff/merge, undo, checkout/connect/release, history, snapshot, doctor and status all support JSON. The former global --api-key, --project-id and --config options were removed because they did not affect execution. Configure MongoDB through MONGODB_URI; configure server auth through ARGON_API_TOKEN.

Projects & branches

argon projects create <name>                   project + main branch
argon projects list
argon branches create <name> -p P [--from B]   instant — a pointer, no copy
argon branches list   -p P
argon branches delete <name> -p P              refused for main, branches with
                                               live children, pinned branches

Work with real databases

argon checkout -p P -b B      materialize into a physical MongoDB database,
                              print its URI (repeat preserves the live database)
argon collections prepare NAME -p P -b B  enable exact images before first writes
argon connect  -p P -b B      print a checked-out branch's URI
argon watch    -p P -b B [--actor A] capture writes with a persisted branch label
argon release  -p P -b B      drop the physical db; history stays
argon proxy [--listen :27018] stable URIs: mongodb://host/<project>~<branch>
argon console [--port 1818]   local web console (REST API + UI), opens browser

While a branch is checked out, its history is fed by watch (or the API/MCP servers' ingesters); SDK writes to it are refused — one source of truth.

Import ("git clone")

argon import preview  --uri U --database D
argon import database --uri U --database D --project P --source-quiesced [--yes]
argon import database --uri U --database D --project P --dry-run
argon import cleanup --project P --yes   # only after stopping a crashed importer
argon import status

Imports auto-snapshot, so reads never replay the whole import. Pause source writers and DDL throughout a real import; --yes does not replace --source-quiesced. Source preflight checks collection types/readability. The target stays unpublished until copying succeeds; ordinary failures clean up the reserved project and history. After a hard kill, stop the old process and use import cleanup before retrying the same name. Completed projects cannot be removed by cleanup. See the import contract.

History: time travel, undo, restore

argon time-travel info  -p P -b B
argon time-travel query -p P -b B --lsn N [-c collection]

argon undo -p P -b B --from-lsn N [--to-lsn M] [--actor A] [--dry-run]
    Revert a range by restoring pre-images — append-only, never rewrites
    history. --actor filters a recorded label; later unselected writes
    are conflicts and skipped. Missing images are reported as unrecoverable.

argon restore preview -p P -b B (--lsn N | --time RFC3339)
argon restore reset   -p P -b B (--lsn N | --time RFC3339) [--backup NAME]
    First stop writers and release a live branch. Rewind the head: discarded entries stay
    for audit; --backup forks the pre-reset head first.
argon restore branch  -p P -b B (--lsn N | --time RFC3339) --as NAME
    Fork the historical state into a new branch instead.

Merge — data pull requests

argon diff          -p P -b B                  what merging B would change
argon merge preview -p P -b B                  persist a reviewable plan
argon merge apply <plan-id> [--strategy theirs|ours]
argon merge list    -p P

Plans apply exactly once and refuse stale parent heads; conflicts fail loudly unless a strategy resolves them. Merges are undoable like any range.

Pins — immutable datasets

argon pin create  -p P [-b B] --name N [--lsn L | --time T] [--note …]
argon pin list    -p P
argon pin delete  -p P --name N
argon pin branch  -p P --name N --as NEW       durable branch from the pin
argon pin sandbox -p P --name N [--ttl 1h]     TTL sandbox from the pin

Pins protect their referenced captured states from GC and resets while they exist. Pin an eval dataset once and fork a sandbox per run for identical document input. Deleting the pin releases that protection; keep independent backups.

Sandboxes — disposable agent branches

argon sandbox create -p P [--from B] [--name N] [--ttl 1h]   fork+checkout+TTL
argon sandbox list / discard / keep / sweep

sweep reaps expired sandboxes (pinned ones skipped loudly); keep removes the TTL. Bare CLI commands do not start background workers. Keep watch running and schedule sweep, or use console/API/MCP managed sandboxes.

Snapshots, GC, agents, migration

argon snapshot create -p P -b B     manual (they're also automatic)
argon snapshot list   -p P -b B
argon gc -p P [--retention 168h] [--dry-run]
    Reclaim entries covered by snapshots, outside retention, and needed
    by no live child or pin. No snapshot → nothing is ever deleted.

argon mcp                           MCP server over stdio (13 tools)
argon migrate-wal --project P [--dry-run]      v1 → v2 schema migration
argon status / metrics              health and performance counters

Readiness and scripting

argon doctor --output json          # actual temporary write/capture probe
argon status --output json          # read-only checks, last reported capture status
argon projects list --output json   # {"projects": [...]}
argon branches list -p P --output json
argon merge preview -p P -b B --output json  # {"plan": {"id": ...}}

Doctor/status return nonzero when readiness fails. A stored capture status is the last report from a worker, not proof that its process is still alive. The CLI does not support relative time on time-travel info; use retained LSNs for queries and RFC3339 timestamps on restore/pin commands.

console binds 127.0.0.1 by default. Non-loopback binding requires ARGON_API_TOKEN unless the restricted hosted demo is explicitly enabled.