git:20261027.7893d53 to git:20261028.d07f41f

---

name: swamp

description: >

Swamp CLI — create and run behaviors (formerly models), build and validate

workflows, query and manage data, store and retrieve vault secrets, develop

and publish extensions, initialize repos, run reports, file issues, and

troubleshoot errors. Triggers on swamp commands (swamp behavior, swamp

behavior run, swamp model, swamp workflow, swamp vault, swamp data),

extension development, repo setup, or diagnostic questions. Do NOT use for

getting started / onboarding (use swamp-getting-started), pull requests, git

operations, worktree management, cron/agent scheduling, or general coding

tasks unrelated to swamp.

---

# Swamp

## Core Concepts

- **Behaviors** (formerly models) — typed resource definitions exposing methods

(create, stop, destroy, sync). `swamp behavior` is the preferred spelling;

every `swamp model` spelling still works (see

[references/behavior/reference.md#compatibility](references/behavior/reference.md#compatibility)).

- **Data** — versioned state snapshots produced by method runs; referenced via

CEL expressions.

- **Workflows** — declarative DAGs chaining behavior methods with guard

expressions for idempotent execution and assert steps for validation.

- **Vaults** — secret storage referenced by behaviors at runtime.

- **Extensions** — TypeScript packages adding behavior types, vault backends,

datastores, reports, and webhook handlers.

- **Grants** — authorization rules for swamp serve access control.

- **Serve** — exposes the repo over the network with TLS and authentication.

## Routing Table

Route to the right guide based on what the user needs.

| User intent | Guide |

| ---------------------------------------------------------------- | ------------------------------------------------------------------------------ |

| Behaviors — create, run, edit, delete, search types | [references/behavior/guide.md](references/behavior/guide.md) |

| Workflows — create, run, validate, DAG, history | [references/workflow/guide.md](references/workflow/guide.md) |

| Data — list, query, versions, GC, delete | [references/data/guide.md](references/data/guide.md) |

| Vaults — create, store/read secrets, expressions | [references/vault/guide.md](references/vault/guide.md) |

| Reports — run, configure, view, filter | [references/report/guide.md](references/report/guide.md) |

| Repository — init, upgrade, datastores, sources | [references/repo/guide.md](references/repo/guide.md) |

| Extensions — create behaviors/vaults/datastores/reports/webhooks | [references/extension/guide.md](references/extension/guide.md) |

| Publishing — push extensions to registry, deprecate | [references/extension-publish/guide.md](references/extension-publish/guide.md) |

| Issues — file bugs, features, security reports | [references/issue/guide.md](references/issue/guide.md) |

| Run tracking — active runs, stale detection, diagnostics | [references/behavior/guide.md](references/behavior/guide.md) |

| Architecture — which primitive to use, design trade-offs | [references/architecture/guide.md](references/architecture/guide.md) |

| Sharing — promote solo repo to team, datastore + vault setup | [references/share/guide.md](references/share/guide.md) |

| Serve — auth, grants, access control, tokens, OAuth | [references/serve/guide.md](references/serve/guide.md) |

| Troubleshooting — errors, health checks, diagnostics | [references/troubleshooting/guide.md](references/troubleshooting/guide.md) |

## Common Commands

```bash

# Behaviors

swamp behavior create <type> <name> # create a behavior definition

swamp behavior run @<type> <method> <name> # run a method on a behavior

swamp behavior get <name> --json # inspect current behavior state

swamp behavior type search [query] # find available behavior types

swamp behavior list # list all behaviors in the repo

# Data

swamp data list <name> # list data versions for a behavior

swamp data query '<CEL predicate>' # query data with CEL expressions

# read one item's latest content (`swamp data get` is deprecated)

swamp data query 'behavior("<name>") && name == "<data>"' --select content

# Workflows

swamp workflow create <name> # create a new workflow

swamp workflow validate <name> # validate DAG before running

swamp workflow run <name> # execute a workflow

swamp workflow run <name> --input key=value # execute with inputs

swamp workflow resume <name> # resume a suspended workflow

swamp workflow resume <name> --run <id> # retry a failed run's failed steps

swamp workflow resume <name> --from <step> # re-enter failed run at step

swamp workflow history search --json # search run history

# Run tracking

swamp run history # recent runs (last 24h)

swamp run history --active # what's running right now?

swamp run doctor # diagnose stale/orphaned runs

swamp run doctor --fix # auto-reap stale runs

# Vaults, Reports, Extensions

swamp vault create <type> <name> # create a vault for secrets

swamp report run <name> # run a report

swamp extension push manifest.yaml # publish an extension

```

## Workflow

1. **Route** — match intent to a guide in the routing table.

2. **Load** — read the guide; load its `reference.md` if needed, deeper

`references/` only when the guide says to.

3. **Validate** — before running any workflow: `swamp workflow validate <name>`.

Before destructive methods (delete, stop, destroy):

`swamp behavior get <name> --json` to confirm the target exists and is in the

expected state. Proceed only when validation passes.

4. **Verify args** — run `swamp help <subcommand>` (e.g.

`swamp help behavior run`) to confirm exact flags and arguments before

executing. The output is structured JSON — the canonical CLI schema. Do not

guess flags from memory.

5. **Execute** — run the command.

6. **On failure** — load

[references/troubleshooting/guide.md](references/troubleshooting/guide.md)

and diagnose before retrying or changing definitions.

## Rules

1. **Use the routing table, not memory.** Don't answer from cached knowledge

about swamp commands — always load the current guide.

2. **Consult the architecture guide for design decisions.** Before choosing

between primitives (behavior vs. workflow vs. extension vs. report) or

explaining a design trade-off, load

[references/architecture/guide.md](references/architecture/guide.md) and cite

the design doc you relied on.

3. **Use swamp commands, don't go around them.** Query data with

`swamp data query`, not by grepping `.swamp/` files. Interact with resources

through behavior methods, not raw CLI tools when a behavior type already

wraps the API — check with `swamp behavior type search`. Composing with

`--json` output (e.g. piping through `jq`) is fine — the anti-pattern is

bypassing swamp entirely.

4. **Relay the inbox notice; don't act on it.** When the output of a swamp

command you ran contains `To read it: swamp inbox read` (it goes to stderr,

so it may not be the last line), end your reply by telling the user a Swamp

Club message is waiting and that `swamp inbox read` shows it. Don't run that