Skip to main content
← Back to list
01Issue
FeatureShippedSwamp Club
Assigneesstack72

Relationships

#907 Add comprehensive CLI command reference documentation to the manual

Opened by stack72 · 7/1/2026· Shipped 7/1/2026

Problem

The manual reference section (content/manual/reference/) has strong coverage of YAML schemas and architectural concepts but almost no CLI command documentation. A user who knows how to write a model definition YAML file cannot discover how to actually run it (swamp model method run), inspect its output (swamp model output), or manage its data (swamp data get/list/versions/gc).

Of the ~20 top-level CLI command groups, only a handful have reference pages (extensions, swamp serve access commands, remote execution worker commands, doctor). The rest — including the three most-used command groups (model, workflow, data) — have zero CLI reference documentation.

Scope

This issue covers reference documentation only (diataxis type: reference). Explanation, how-to, and tutorial gaps are tracked separately.

The reference section currently has 18 top-level tiles in the manual navigation. Naively adding one page per CLI command group would push this to 30+, making the reference section unusable. The strategy below avoids this by:

  1. Integrating CLI commands into existing concept pages where a natural home exists (e.g., add swamp vault create/put/get/... to the existing Vaults reference page rather than creating a separate "Vault Commands" page).
  2. Merging related pages that are currently separate but cover the same domain (e.g., "Data Outputs" and "Data Querying" into one "Data" page).
  3. Creating one consolidated page for operational commands that have no existing home (repo, auth, config, audit, summarise, telemetry, update, source, completions, issue, agent) rather than 11 separate pages.
  4. Using sub-pages only for genuinely complex command groups that would make their parent page too long (the existing pattern for extensions/, remote-execution/, swamp-serve/*).

Target: the reference section should have fewer top-level tiles after this work than it does today, despite covering significantly more content.

Detailed Plan

Phase 1: Consolidate Existing Pages (reduces tile count)

These changes reduce navigation clutter before adding new content.

1.1 Merge "model type describe" into "Model Definitions"

The model type describe page (reference/model-type-describe.md, order 2) is a CLI command reference for a single subcommand. It belongs as a section within the "Model Definitions" page (reference/model-definitions.md, order 2), which already covers the YAML schema that model type describe inspects.

  • Move the content of model-type-describe.md into a ## model type describe section at the end of model-definitions.md
  • Also add a ## model type search section (currently undocumented)
  • Delete model-type-describe.md
  • Net tile change: -1

1.2 Merge "Data Querying" into "Data Outputs" → rename to "Data"

"Data Outputs" (reference/data-outputs.md, order 5) covers data specs, lifetime, GC, versioning, streaming, tags, and sensitive fields. "Data Querying" (reference/data-querying.md, order 8) covers swamp data query, CEL predicates, --select projections, and the TUI.

These are two halves of the same topic. Merge into one page:

  • Rename data-outputs.md to data.md with title "Data"
  • Move content from data-querying.md into a ## Querying section
  • Delete data-querying.md
  • Update the description to cover both output specs and querying
  • Net tile change: -1

1.3 Merge "Namespace Commands" into "Datastore Configuration"

"Namespace Commands" (reference/namespace-commands.md, order 9) documents swamp datastore namespace set/unset/migrate/list. These are subcommands of swamp datastore and belong in the "Datastore Configuration" page (reference/datastore-configuration.md, order 8).

  • Move content into a ## Namespace Commands section in datastore-configuration.md
  • Delete namespace-commands.md
  • Net tile change: -1

Phase 1 total: -3 tiles (18 → 15 top-level reference tiles)

Phase 2: Add CLI Commands to Existing Pages

Each existing concept page gets a new section documenting the CLI commands for that domain. The pattern for each command entry is:

### `swamp <command> <subcommand>`

<one-line description>

**Usage:** `swamp <command> <subcommand> <args> [flags]`

| Flag | Default | Description |
|------|---------|-------------|
| ... | ... | ... |

**Output (JSON):** <key fields in the JSON output>

**Exit codes:** 0 success, 1 error (or specific codes if they differ)

**Examples:**
\```bash
swamp <command> <subcommand> <args>
\```

2.1 Model Definitions (reference/model-definitions.md) — add CLI commands section

Add a ## CLI Commands section documenting:

  • swamp model create <type> <name> — create a new model definition. Flags: --repo-dir, --server, --token, --global-arg, --force. Explain what files it creates, where definitions are stored (models/ vs .swamp/auto-definitions/), and the auto-creation behavior when using @type prefix with method run.
  • swamp model get <name> --json — show model definition details. Document the JSON shape (id, name, type, version, globalArguments, methods, dataOutputs, checks, reports, tags).
  • swamp model search [query] — search for model definitions. Flags: --type, --tag, --limit. Document search behavior (name, type, tag matching).
  • swamp model edit [name] — open model definition in $EDITOR. Document file resolution behavior.
  • swamp model delete <name> — delete model and all related artifacts. Document what gets deleted (definition, outputs, data). Flags: --force.
  • swamp model validate [name] — validate definition against schema. Document what it checks (schema, method args, check resolution, output spec validity). Flags: --skip-check.
  • swamp model evaluate [name] — evaluate CEL expressions in the definition. Document what gets evaluated and the output format.
  • swamp model cancel [name] — cancel a running method run. Document signal handling.

Source of truth for flags and behavior: Run swamp help model for the JSON schema of all model subcommands. Cross-reference with actual CLI output by running each command in a sandbox repo.

2.2 Model Definitions — add method execution section

Add a ## Method Execution section (or sub-page reference/model-methods.md if it makes the page too long — use judgment based on final length):

  • swamp model method run <model_or_type> <method> [definition_name] — the single most important command in swamp. Document:
    • Positional args: model name or @type prefix for auto-creation
    • Input flags: --input key=value, --input-file <path>, --stdin
    • Execution flags: --tag key=value, --skip-check, --skip-check-label, --timeout
    • Server flags: --server, --token
    • Report flags: --report, --skip-report, --skip-report-label, --skip-reports
    • Output format: what the interactive tree shows, what --json returns
    • Exit codes: 0 success, non-zero with specific meaning
    • The relationship between method run → data output → data versioning
  • swamp model method describe <model> <method> — inspect method arguments, output specs, checks. Document the JSON shape.
  • swamp model method history get/search/logs <model> — execution history. Document fields (run ID, status, duration, timestamps, error).

2.3 Model Definitions — add output management section

Add a ## Output Management section:

  • swamp model output get <model> — show latest output. Flags: --run, --output-id. JSON shape.
  • swamp model output search [query] — search outputs. Flags: --model, --status, --since, --tag.
  • swamp model output logs <output_id> — show log artifacts.
  • swamp model output data <output_id> — show data artifacts.

2.4 Data page (after Phase 1 merge) — add CLI commands

Add a ## CLI Commands section to the merged Data page:

  • swamp data get [model] [data_name] — retrieve a specific data artifact. Flags: --workflow, --run, --no-content. JSON shape including attributes, metadata, provenance.
  • swamp data list [model] — list data grouped by type. Flags: --workflow, --limit. Document the grouping (resources vs files).
  • swamp data search [query] — search across all models. Flags: --type, --lifetime, --owner-type, --workflow, --model, --content-type, --since, --output, --run, --tag, --streaming, --limit.
  • swamp data versions [model] [data_name] — list all versions. Document version numbering, timestamps, diff.
  • swamp data gc — garbage collection. Flags: --dry-run, --force. Document what GC removes (expired lifetime, excess versions).
  • swamp data rename [model] [old] [new] — rename with backwards-compatible forwarding. Document the forwarding mechanism.
  • swamp data delete [model] [data_name] — delete artifacts. Flags: --prefix, --all, --dry-run, --force. Document the three deletion modes (by name, by prefix, all for model).

2.5 Workflows (reference/workflows.md) — add CLI commands

Add a ## CLI Commands section:

  • swamp workflow create <name> — create workflow file. Document where it's created (workflows/).
  • swamp workflow run <name> — execute a workflow. Flags: --input, --input-file, --stdin, --tag, --skip-checks, --skip-check, --skip-check-label, --skip-reports, --skip-report, --skip-report-label, --report, --report-label, --timeout, --server, --token, --last-evaluated. Document the interactive tree output and --json shape.
  • swamp workflow get <name> — show workflow definition details. JSON shape.
  • swamp workflow search [query] — search for workflows.
  • swamp workflow edit [name] — open in $EDITOR.
  • swamp workflow delete <name> — delete workflow and run history. Flags: --force.
  • swamp workflow validate [name] — validate schema, dependencies, method resolution. Document what each check verifies.
  • swamp workflow evaluate [name] — test CEL expressions.
  • swamp workflow cancel [name] — cancel a running run.
  • swamp workflow schema get — get the YAML schema for workflow files.

Add a ## Approval Commands section:

  • swamp workflow approve <name> <step> — approve a manual approval step. Flags: --reason, --server, --token.
  • swamp workflow reject <name> <step> — reject. Flags: --reason.
  • swamp workflow resume <name> — resume after approval.
  • swamp workflow approvals — list all pending approvals. JSON shape.

Add a ## History section:

  • swamp workflow history get <name> — show latest run. JSON shape.
  • swamp workflow history search [query] — search past runs. Flags: --since, --status, --workflow, --tag, --limit.
  • swamp workflow history logs <run_id> — show logs for a run.
  • swamp workflow run search [query] — alias for history search.

2.6 Vaults (reference/vaults.md) — add CLI commands

Add a ## CLI Commands section:

  • swamp vault create <type> [name] — create a vault configuration. Document the interactive flow and --type behavior.
  • swamp vault search [query] — search for vaults.
  • swamp vault get <name> [extra] — show vault details. JSON shape.
  • swamp vault describe <name> — describe vault configuration.
  • swamp vault edit [name] — open config in $EDITOR.
  • swamp vault put <name> <key> [value] — store a secret. Document: interactive prompt when value omitted, stdin support, KEY=VALUE format. Flags: --force, --refresh-from, --refresh-ttl, --clear-refresh.
  • swamp vault read-secret <name> <key> — read a secret value. Flags: --force.
  • swamp vault delete <name> <key> — delete a secret.
  • swamp vault annotate <name> <key> — add metadata. Flags: --url, --notes, --label, --clear, --remove-label.
  • swamp vault inspect <name> <key> — show metadata without exposing value. Document what's shown (size, type, annotations, refresh hooks).
  • swamp vault list-keys [name] — list all keys without values.
  • swamp vault migrate <name> — migrate to different backend. Flags: --to-type, --config, --dry-run, --force.
  • swamp vault type search [query] — search available vault types (from extensions).

2.7 Datastore Configuration (reference/datastore-configuration.md) — add CLI commands

Add a ## CLI Commands section (in addition to the namespace commands merged in Phase 1):

  • swamp datastore status — show configuration and health. Flags: --repo-dir, --server, --token. JSON shape.
  • swamp datastore setup filesystem — set up filesystem datastore. Flags: --path, --directories, --skip-migration, --repo-dir.
  • swamp datastore setup extension <type> — set up extension-provided datastore. Flags: --config, --skip-migration, --hydration-strategy, --repo-dir.
  • swamp datastore sync — sync local cache with remote datastore. Flags: --pull, --push, --timeout, --repo-dir.
  • swamp datastore compact — checkpoint WAL and vacuum catalog. Flags: --repo-dir.
  • swamp datastore lock status — show who holds the lock. Flags: --repo-dir.
  • swamp datastore lock release — force-release a stuck lock. Flags: --force, --model, --repo-dir.
  • swamp datastore catalog pull — pull catalog from foreign namespaces. Flags: --namespaces, --repo-dir.
  • swamp datastore type search [query] — search available datastore types.

2.8 Extensions reference pages — add missing command docs

The extensions section already has reference/extensions/management.md covering pull/install/update/outdated/rm/info/version and reference/extensions/publishing.md covering push/fmt/quality. Add to these:

In management.md:

  • swamp extension trust list — list trusted collectives
  • swamp extension trust add <collective> — add to trusted list
  • swamp extension trust rm <collective> — remove from trusted list
  • swamp extension trust auto-trust <enabled> — enable/disable auto-trust for membership collectives
  • swamp extension source list — list configured local sources
  • swamp extension source add <path> — add local source
  • swamp extension source rm <path> — remove local source

In publishing.md:

  • swamp extension yank <extension> [version] — yank from registry. Flags: --reason, --channel, --yes.
  • swamp extension unyank <extension> [version] — restore availability.
  • swamp extension deprecate <extension> — deprecate. Flags: --reason, --superseded-by, --yes.
  • swamp extension undeprecate <extension> — remove deprecation.
  • swamp extension promote <extension> <version> — promote release channel. Flags: --channel, --from-channel. Document the channel ladder (beta→rc→stable).

2.9 API Key Authentication (reference/api-key-authentication.md) — add auth commands

Add a ## CLI Commands section:

  • swamp auth login — authenticate with swamp-club. Flags: --server, --username, --password, --no-browser. Document the device flow (browser opens, code displayed).
  • swamp auth logout — remove stored credentials. Document what's removed.
  • swamp auth whoami / swamp auth status — show current identity. JSON shape (user ID, username, email, collectives).
  • swamp auth server-login — store a server token for swamp serve. Flags: --server, --token. Document credential storage location.

2.10 Repository Configuration (reference/repository-configuration.md) — add repo commands

Add a ## CLI Commands section:

  • swamp repo init [path] — initialize a new repository. Flags: --force, --tool. Document what it creates (.swamp/, .swamp.yaml, tool-specific files like CLAUDE.md, .cursor/), and the tool selection interactive flow.
  • swamp repo upgrade [path] — upgrade an existing repository. Flags: --tool, --include-gitignore. Document what it upgrades (skills, instructions, audit hooks).
  • swamp update — update swamp to latest version. Flags: --check, --setup-auto. Document the update process and how --setup-auto configures background autoupdating.
  • swamp completions bash/fish/zsh — generate shell completions. Flags: --name. Document installation instructions for each shell.
  • swamp config get <key> — get a configuration value.
  • swamp config set <key> <value> — set a configuration value.
  • swamp config list — list all configuration keys and their current values. Document known config keys and their purpose.

2.11 Doctor (reference/doctor.md) — verify completeness

The Doctor reference page already exists. Verify it covers all subcommands with flags and JSON output shapes. If any are missing, add them:

  • swamp doctor audit — Flags: --tool, --repo-dir, --server, --token.
  • swamp doctor extensions — Flags: --repo-dir, --verbose, --repair, --dry-run, --force.
  • swamp doctor install — no extra flags.
  • swamp doctor secrets — Flags: --repo-dir, --server, --token.
  • swamp doctor vaults — Flags: --repo-dir, --server, --token.
  • swamp doctor workflows — Flags: --repo-dir, --server, --token.

Phase 3: New Pages for Orphaned Commands (+2 tiles)

Only two genuinely new reference pages are needed for command groups that have no existing home.

3.1 NEW: "Operational Commands" (reference/operational-commands.md)

A consolidated page covering day-to-day operational CLI commands that don't belong to a specific domain:

  • swamp audit — view audit timeline. Flags: --repo-dir, --hours, --all, --session, --include-diagnostic, --server, --token. Document the output format (timeline of swamp vs direct CLI commands).
  • swamp summarise / swamp summarize — repo activity overview. Flags: --repo-dir, --since, --limit, --server, --token. Document the output sections (method executions, workflows, data).
  • swamp telemetry stats — usage statistics. Flags: --repo-dir, --days. Document what's shown.
  • swamp source fetch — download swamp source from GitHub for troubleshooting.
  • swamp source path — show source location and version.
  • swamp source clean — remove downloaded source.

3.2 NEW: "Issue Commands" (reference/issue-commands.md)

Document the swamp issue command group for interacting with swamp-club Lab:

  • swamp issue search [query] — search issues. Flags: --type, --status, --source, --limit. JSON shape.
  • swamp issue get <number> — fetch issue details. JSON shape (title, type, status, author, body, assignees, comments).
  • swamp issue edit <number> — edit title/body. Flags: --title, --body. Permission model (author or admin only).
  • swamp issue bug — submit bug report. Flags: --title, --body, --email, --extension, --repo-dir. Document template fields.
  • swamp issue feature — submit feature request. Same flags. Document template fields.
  • swamp issue security — submit security report. Same flags. Document visibility (author and admins only).
  • swamp issue ripple <number> / swamp issue comment <number> — post a comment. Flags: --body, --close, --reopen.

Phase 4: swamp serve Webhook Reference (sub-page, +0 tiles)

Add a new sub-page reference/swamp-serve/webhooks.md documenting the --webhook flag in detail. This is currently a single flag line but represents a significant feature:

  • Webhook spec format: <route>:<workflow>:<secret>[:<scheme>[:<header>[:<prefix>]]]
  • Supported provider schemes: github (default), linear, stripe, slack, generic
  • Secret sources: literal string, @env=VAR, @file=/path
  • Signature verification per provider (HMAC-SHA256 for GitHub, etc.)
  • How webhook payloads are exposed in workflow CEL expressions (webhook.*)
  • Examples for each provider scheme
  • Error handling and response codes

This is a sub-page under the existing swamp-serve/ directory, so it adds zero new top-level tiles.

Summary of Tile Changes

Change Tiles
Phase 1: merge model-type-describe -1
Phase 1: merge data-querying into data-outputs -1
Phase 1: merge namespace-commands into datastore -1
Phase 2: add CLI commands to existing pages +0
Phase 3: new "Operational Commands" page +1
Phase 3: new "Issue Commands" page +1
Phase 4: webhook sub-page (under swamp-serve/) +0
Net change -1

Final tile count: 17 top-level reference tiles (down from 18), covering significantly more content.

Implementation Notes

How to verify CLI commands

For every command documented, the implementing agent must:

  1. Run swamp help <command path> to get the authoritative JSON schema (flags, arguments, types, defaults)
  2. Create a sandbox repo (SWAMP_SANDBOX=$(mktemp -d) && cd "$SWAMP_SANDBOX" && swamp repo init) and run each command to verify actual output
  3. Use --json output to document JSON shapes
  4. Cross-reference flags between swamp help output and swamp <command> --help output

Page structure conventions

Follow the existing reference page patterns in content/manual/reference/:

  • Frontmatter: title, description (150-160 chars), type: reference, order
  • Use tables for flag documentation
  • Use fenced code blocks for JSON output shapes and examples
  • Keep descriptions factual and terse — this is reference, not explanation
  • Don't explain why (that's for explanation pages) — document what and how

Terminology

  • "Swamp" capitalized in prose, swamp lowercase in command invocations (per CLAUDE.md rules)
  • "operative" not "operator" for users
  • "collective" not "organization"

Acceptance Criteria

  • Phase 1 merges completed: model-type-describe.md, data-querying.md, and namespace-commands.md deleted; content integrated into parent pages
  • Every CLI command listed in swamp --help has reference documentation in the manual
  • Every command entry includes: usage line, flag table (from swamp help), JSON output shape (from --json), at least one example
  • All command documentation is verified against actual CLI output in a sandbox repo
  • Top-level reference tile count is <= 18 (no increase from current)
  • deno task check passes
  • Internal links between pages are valid (no broken cross-references from merges)
  • Frontmatter description fields are 150-160 chars and unique per page
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 3 MOREREVIEW+ 4 MOREPR_MERGED+ 1 MORENOTIFICATION_SKIPPED

Shipped

7/1/2026, 7:16:46 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack727/1/2026, 6:02:32 PM

Sign in to post a ripple.