MANAGEMENT

swamp provides commands for managing the extensions installed in a repository. This reference describes each command — arguments, flags, exit codes, output, and JSON shape. Publishing-side commands (push, fmt, quality, promote) and governance commands (yank, unyank, deprecate, undeprecate) are covered in Publishing Commands.

All commands accept the standard global flags (--json, --log, --no-color, --quiet, --verbose, --no-telemetry, --log-level, --show-properties, -h/--help). Only command-specific arguments and flags are listed below.

Remote execution (--server)

All extension management commands accept --server and --token to target a remote swamp serve instance:

list

Aliases: ls.

Lists upstream extensions installed in the current repository.

Flags

Output (no extensions installed)

extension·list: No upstream extensions installed.
extension·list: Use 'swamp extension pull @namespace/name' to install one.

Output (installed)

extension·list: "@swamp/gcp/run           v2026.04.23.1  (pulled 2026-05-01T16🔞14.385Z)"
extension·list: "@swamp/gcp/workstations  v2026.05.01.1  (pulled 2026-05-01T16🔞09.750Z)"

A tag after the version shows the channel the registry lists it on, then the followed channel when they differ. An install that follows stable and is published on stable has no tag:

extension·list: "@hivemq/asdlc            v2026.10.13.1791925735 [beta, following stable]  (pulled 2026-10-14T00:31:44.209Z)"
extension·list: "@swamp/software-factory  v2026.10.13.1                                    (pulled 2026-10-14T00:30:56.217Z)"

Output (with --check-updates)

A second version column is added; entries with an available update get an (update available) annotation.

extension·list: "@swamp/1password  v2026.03.17.1  v2026.04.22.2  (update available)  (pulled 2026-05-01T17:10:40.846Z)"
extension·list: "@swamp/gcp/run    v2026.04.23.1  v2026.04.23.1  (pulled 2026-05-01T17:10:45.720Z)"

JSON shape

Without --check-updates:

{
  "extensions": [
    {
      "name": "@swamp/gcp/run",
      "version": "2026.04.23.1",
      "pulledAt": "2026-05-01T16🔞14.385Z",
      "files": [
        ".swamp/pulled-extensions/@swamp/gcp/run/models/services.ts",
        "..."
      ],
      "publishedChannel": "stable"
    }
  ]
}

channel is the channel the install follows; it is omitted for stable. publishedChannel is the channel the registry listed the installed version on when it was pulled; it is omitted when the lockfile does not record one.

With --check-updates, each entry gains two additional fields, latestVersion and updateStatus:

{
  "name": "@swamp/gcp/run",
  "version": "2026.04.23.1",
  "pulledAt": "2026-05-01T16🔞14.385Z",
  "files": ["..."],
  "latestVersion": "2026.04.23.1",
  "updateStatus": "up_to_date"
}

When the registry is unreachable, latestVersion is null and updateStatus is unknown_offline:

{
  "name": "@swamp/gcp/run",
  "version": "2026.04.23.1",
  "pulledAt": "2026-05-01T17:12:13.083Z",
  "files": ["..."],
  "latestVersion": null,
  "updateStatus": "unknown_offline"
}

updateStatus values:

search

Searches the Swamp extension registry.

Arguments

[query] — optional search term. Empty query returns the full registry page.

Flags

--channel accepts multiple values (--channel rc --channel beta) to include results from more than one prerelease channel. Omitting --channel returns stable-only results.

--content-type behaviors is sent to the registry as models, the content type the registry records for behavior extensions; contentTypes in the output reads models. Any other value fails with Invalid content type: "<value>". Must be one of: models, workflows, vaults, datastores, reports (behaviors is accepted for models).

Output

Returns a page of registry entries. Each entry includes name, description, latestVersion, createdAt, updatedAt, platforms, labels, and contentTypes. Results are paginated; the response includes a meta block with total, page, and perPage.

JSON shape

{
  "query": "@swamp",
  "extensions": [
    {
      "name": "@swamp/1password",
      "description": "Read and write secrets stored in 1Password using the `op` CLI...",
      "latestVersion": "2026.04.22.2",
      "createdAt": "2026-03-17T18:38:46.943Z",
      "updatedAt": "2026-04-22T22:42:35.914Z",
      "platforms": [],
      "labels": ["vault", "1password", "secrets"],
      "contentTypes": ["vaults"]
    }
  ],
  "meta": {
    "total": 575,
    "page": 1,
    "perPage": 20
  }
}

pull

Pulls an extension from the Swamp registry into the current repository and records it in the lockfile at extensions/models/upstream_extensions.json.

Arguments

<extension> — extension name (e.g. @swamp/gcp/workstations). The @name@version form pulls a specific published version.

Flags

When --channel is specified, pull fetches the latest version from that channel. With an exact version (@name@version), pull installs that version whatever channel it is published on, and --channel sets only the channel the install follows.

The lockfile records two channels for each install:

The two differ when an exact version is pulled from another channel, or when the version was promoted after it was pulled.

Pulling a beta or rc version while the install follows stable installs it and logs a warning naming the command that follows its channel:

extension·pull: @hivemq/asdlc@2026.10.13.1791925735 is a beta release, and --channel was not passed: swamp extension update keeps following stable for @hivemq/asdlc. Run swamp extension pull @hivemq/asdlc --channel beta to follow beta.

When the version is pulled as a dependency, the warning says installed because <parent> pins it in place of and --channel was not passed.

Output

extension·pull: Pulling "@swamp/gcp/workstations"@"2026.05.01.1"
extension·pull: Description: "Google Cloud workstations infrastructure models"
extension·pull: Identity verified: "@swamp/gcp/workstations"@"2026.05.01.1"
extension·pull: Repository: "https://github.com/systeminit/swamp-extensions"
extension·pull: Safety warnings:
extension·pull:   "...models/workstationclusters_workstationconfigs.ts": "File contains lines with more than 500 non-whitespace characters."
extension·pull: Pulled "@swamp/gcp/workstations"@"2026.05.01.1"
extension·pull: Extracted 12 files:
extension·pull:   ".swamp/pulled-extensions/@swamp/gcp/workstations/models/locations.ts"
extension·pull:   "..."

Files are extracted to .swamp/pulled-extensions/<extension>/ and bundled artifacts are written to .swamp/bundles/<hash>/. Pull keeps the bundles the publisher built, after checking each against the digest in the archive's dependency-audit.json; see Extension Dependencies § What consumers run.

When the pulled extension contains foreign-type grafts — methods added to types it does not define — a warning is displayed:

extension·pull: Extension grafts methods onto types it does not define:
extension·pull:   "@acme/base-model" — methods: "custom_sync"

This warns that the extension modifies the behavior of another extension's types. The pull still succeeds; the warning is informational.

Output (replacing an installed extension)

Before replacing an installed extension, pull logs what is installed, what is incoming, and how they relate. Each side shows the channel the registry lists the version on, then the followed channel when it differs:

extension·pull: @hivemq/asdlc: installed 2026.10.13.1791920052 (stable) -> incoming 2026.10.13.1791925735 (beta, following stable)
extension·pull: Upgrade: 2026.10.13.1791925735 is newer than the installed 2026.10.13.1791920052. Channel change: stable to beta.

The second line starts with one of:

Channel change: <from> to <to>. is appended when both published channels are known and differ.

Without --yes, the summary is followed by the files that will be overwritten and a prompt that says what each answer does:

extension·pull: @x/y: installed 2026.09.23.1 (stable) -> incoming 2026.10.01.1 (beta, following stable)
extension·pull: Upgrade: 2026.10.01.1 is newer than the installed 2026.09.23.1. Channel change: stable to beta.
extension·pull: The following files already exist and will be overwritten:
extension·pull:   ...
  y = replace 2026.09.23.1 (stable) with 2026.10.01.1 (beta)
  N = exit; nothing is changed
Overwrite existing files? [y/N]

With --yes or --force, the summary is logged and the pull goes ahead without the prompt.

JSON shape

--json emits a stream of JSON objects, one per pull stage (identity, integrity, repository, warnings, summary). Each object is written as a standalone document — the stream is not wrapped in an outer array.

{
  "name": "@swamp/gcp/run",
  "version": "2026.04.23.1",
  "description": "Google Cloud run infrastructure models",
  "channel": "stable",
  "publishedChannel": "stable",
  "previous": null
}
{
  "integrity": "verified",
  "name": "@swamp/gcp/run",
  "version": "2026.04.23.1"
}
{
  "repository": "https://github.com/systeminit/swamp-extensions"
}
{
  "warnings": [
    {
      "file": "...",
      "message": "File uses Deno.Command() to spawn subprocesses."
    }
  ]
}
{
  "name": "@swamp/gcp/run",
  "version": "2026.04.23.1",
  "extractedFiles": ["..."]
}

The warnings document is omitted when the pulled archive triggers no safety warnings.

The first document also says what the pull replaced. On a first install, previous is null and change and channelChanged are omitted.

A replacement that changes channel:

{
  "name": "@hivemq/asdlc",
  "version": "2026.10.13.1791920052",
  "description": "Agent-friendly Software Development Lifecycle models",
  "channel": "stable",
  "publishedChannel": "stable",
  "previous": {
    "version": "2026.10.13.1791925735",
    "channel": "stable",
    "publishedChannel": "beta"
  },
  "change": "downgrade",
  "channelChanged": true
}

Without --yes, a pull that would replace files prints a conflict document and exits with Files already exist. Use --force to overwrite.. The document names the extension, both sides as {version, channel, publishedChannel}, the change and channelChanged; current is null when the installed version cannot be determined:

{
  "name": "@hivemq/asdlc",
  "current": {
    "version": "2026.10.13.1791925735",
    "channel": "stable",
    "publishedChannel": "beta"
  },
  "incoming": {
    "version": "2026.10.13.1791920052",
    "channel": "stable",
    "publishedChannel": "stable"
  },
  "change": "downgrade",
  "channelChanged": true,
  "conflicts": [
    ".swamp/pulled-extensions/@hivemq/asdlc/models/asdlc/check-ci.ts",
    "..."
  ]
}

install

Restores all extensions listed in the repository's lockfile at extensions/models/upstream_extensions.json at their pinned versions. Used after cloning a repository.

Flags

Output (no work to do)

extension·install: Reading lockfile...
extension·install: All extensions up to date.

JSON shape

{
  "entries": [
    {
      "name": "@swamp/gcp/run",
      "version": "2026.04.23.1",
      "status": "up_to_date"
    }
  ],
  "installed": 0,
  "migrated": 0,
  "upToDate": 1,
  "failed": 0
}

update

Updates installed extensions to their latest versions. With no argument, operates on every installed extension. With an extension name, operates on that extension only.

Arguments

[extension] — optional extension name to update. If omitted, every installed extension is included.

Flags

Output (--check, all up to date)

extension·update: "@swamp/gcp/workstations  v2026.05.01.1  (up to date)"
extension·update: "@swamp/gcp/run           v2026.04.23.1  (up to date)"
extension·update:
All extensions are up to date.

Output (no --check, all up to date)

extension·update: "@swamp/gcp/workstations: already up to date (v2026.05.01.1)"
extension·update: "@swamp/gcp/run: already up to date (v2026.04.23.1)"
extension·update:
"2 extension(s): 0 updated, 2 up to date, 0 failed"

Output (no --check, updates pulled)

extension·update: Updating "@swamp/1password": v"2026.03.17.1" -> v"2026.04.22.2"
extension·update: "Updated @swamp/1password: v2026.03.17.1 -> v2026.04.22.2"
extension·update: "@swamp/gcp/run: already up to date (v2026.04.23.1)"
extension·update:
"2 extension(s): 1 updated, 1 up to date, 0 failed"

JSON shape (--check)

--json --check returns a single document. Per-extension status is up_to_date when the installed version matches the registry, or update_available when the registry has a newer version. Both states use the same fields.

{
  "extensions": [
    {
      "status": "update_available",
      "name": "@swamp/1password",
      "installedVersion": "2026.03.17.1",
      "latestVersion": "2026.04.22.2"
    }
  ],
  "summary": {
    "total": 1,
    "upToDate": 0,
    "updated": 0,
    "failed": 0
  }
}

JSON shape (no --check, updates pulled)

--json without --check emits a stream of JSON objects. One progress document per extension being updated, then a final summary document. The summary's per-extension entries use previousVersion and newVersion (not installedVersion/latestVersion) when the entry was actually updated.

{
  "status": "updating",
  "name": "@swamp/1password",
  "from": "2026.03.17.1",
  "to": "2026.04.22.2"
}
{
  "extensions": [
    {
      "status": "updated",
      "name": "@swamp/1password",
      "previousVersion": "2026.03.17.1",
      "newVersion": "2026.04.22.2"
    }
  ],
  "summary": {
    "total": 1,
    "upToDate": 0,
    "updated": 1,
    "failed": 0
  }
}

Entries that were already up to date appear in the same summary document with status: "up_to_date" and installedVersion/latestVersion fields instead.

Examples

swamp extension update                  # update all
swamp extension update @stack72/aws-ec2 # update one
swamp extension update --check          # show what is outdated, do not pull

outdated

Lists installed extensions whose registry version is newer than the installed version.

Flags

Exit codes

Status values

Up-to-date extensions are omitted from extensions[] — an empty array means all extensions are up to date. Entries that appear in extensions[] carry one of these status values:

Output (all up to date)

extension·outdated: All extensions are up to date.

Output (updates available)

extension·outdated: "@swamp/1password  v2026.03.17.1 -> v2026.04.22.2  (update available)"
extension·outdated:
1 update(s) available. Run 'swamp extension update' to update.

JSON shape (all up to date)

{
  "extensions": [],
  "hasUpdateAvailable": false
}

JSON shape (updates available)

Entries in extensions[] have status, name, installedVersion, and latestVersion. These fields differ from list's --check-updates shape, which uses version, updateStatus, pulledAt, and files.

{
  "extensions": [
    {
      "status": "update_available",
      "name": "@swamp/1password",
      "installedVersion": "2026.03.17.1",
      "latestVersion": "2026.04.22.2"
    }
  ],
  "hasUpdateAvailable": true
}

JSON shape (registry lookup failure)

not_found and failed entries include an error field describing the failure. They appear in extensions[] but do not affect hasUpdateAvailable.

{
  "extensions": [
    {
      "status": "not_found",
      "name": "@swamp/gcp/run",
      "installedVersion": "2026.04.23.1",
      "error": "Failed to fetch registry info for @swamp/gcp/run."
    }
  ],
  "hasUpdateAvailable": false
}

Examples

swamp extension outdated           # list outdated extensions
swamp extension outdated && deploy # CI gate: deploy only when all up to date

rm

Aliases: remove.

Removes a pulled extension and its files from the repository. Updates the lockfile.

Arguments

<extension> — extension name to remove.

Flags

Output

Without --yes:

Remove @swamp/gcp/run (v2026.04.23.1)? This will delete 20 file(s). [y/N]

With --yes:

extension·rm: Removed "@swamp/gcp/run" (v"2026.04.23.1") — deleted 20 file(s)
extension·rm: Pruned 5 empty directory(ies)

JSON shape

{
  "removed": {
    "name": "@swamp/gcp/run",
    "version": "2026.04.23.1",
    "filesDeleted": 20,
    "filesSkipped": 0,
    "dirsRemoved": 5
  }
}

info

Shows full registry metadata for a specific extension, including author, content listings, download count, quality score, and per-channel latest versions when prerelease versions exist.

Arguments

<name> — extension name (e.g. @swamp/gcp/run).

Output

The default output shows a summary line per content entry (behavior type and method names, vault type and description, etc.):

extension·info: "@swamp/gcp/run" ("2026.06.25.1")
extension·info: "Google Cloud run infrastructure models"
extension·info:
extension·info: Author:      "Paul Stack" ("stack72")
extension·info: Collective:  "@swamp"
extension·info: Repository:  "https://github.com/swamp-club/swamp-extensions" (verified)
extension·info:
extension·info: Labels:      "gcp, google-cloud, run, cloud, infrastructure"
extension·info: Contents:    "models"
extension·info: Exports:     "locations, services, jobs, ..."
extension·info:
extension·info: Behaviors (25):
extension·info:   "@swamp/gcp/run/locations" — methods: "get, sync, list"
extension·info:   "@swamp/gcp/run/services" — methods: "create, get, update, delete, sync, list, ..."
extension·info:   ...
extension·info:
extension·info: Downloads:   52
extension·info: Quality:     "A" (100%)
extension·info:
extension·info: Created:     "2026-03-27T23:29:00.394Z"
extension·info: Updated:     "2026-06-25T14:45:56.820Z"

The content section heading reflects the extension's content type — Models for behavior extensions, Vaults for vault extensions, and so on. Extensions that bundle multiple content types show one section per type.

When an extension contains foreign-type grafts — methods added to types defined by other extensions via export const extension — an Extends section appears after the content sections:

extension·info: Extends (1):
extension·info:   "@acme/base-model" — methods: "custom_sync, custom_report"

Each line lists the target type that the extension grafts methods onto, followed by the grafted method names. The Extends section is omitted when the extension has no foreign-type grafts.

The registry stores a version's grafts at push and serves them as extensions, an array of { fileName, extendsType, methods, resources }, on the version detail (GET /api/v1/extensions/{name}@{version}) and on latestVersionDetail from GET /api/v1/extensions/{name}/latest; the extension page lists them under Extends. A version pushed before the registry stored grafts carries an empty list, so its Extends section is omitted until a new version is pushed.

When the latest version declared acceptances, an Accepted warnings block appears after the content sections and before Downloads. It lists the warnings the author accepted, in the line format of the Accepted warnings: block that push prints (see Publishing § Report):

extension·info: Accepted warnings:
extension·info:   generated by swamp-extensions/codegen from https://api.example.com/openapi.yaml at 0123abcd
extension·info:   ipv4-address-literals — models/hosts.txt:2: documented lab addresses
extension·info:   testing-completeness — models/ext/accepted.ts
extension·info:   credentials-sensitive-field — models/ext/accepted.ts:13: a placeholder the docs example fills in
extension·info:   credentials-sensitive-field — models/ext/accepted.ts:14

• The generated by line appears when the version declared generated code.
• Each entry is the rule, an em dash, then file:line, the file alone, or (extension) when the entry has no file, followed by : <reason> when the author gave one.
• Files are archive paths (models/...). Control characters in text the author wrote are escaped.
• and <n> more ends the block when the version declared more entries than the registry returned; the registry keeps the first 500.

Output (with --verbose)

The global --verbose flag expands each content entry with method signatures and descriptions (for behaviors) or configuration fields (for vaults):

extension·info: Behaviors (25):
extension·info:   "@swamp/gcp/run/locations" — methods: "get, sync, list"
extension·info:     "get"("identifier:string")
extension·info:       "Get a locations"
extension·info:     "sync"("")
extension·info:       "Sync locations state from GCP"
extension·info:     "list"("extraLocationTypes?:string, filter?:string, pageSize?:number, maxPages?:number")
extension·info:       "List locations resources"
extension·info:   ...

JSON shape

--json returns the full registry record. The contentMetadata object contains per-content-type arrays with method signatures, argument schemas, and configuration fields extracted from the extension's source at publish time.

{
  "id": "43676b65-2916-405c-aaf4-a8115bd21c6a",
  "name": "@swamp/gcp/run",
  "namespace": "@swamp",
  "description": "Google Cloud run infrastructure models",
  "repository": "https://github.com/swamp-club/swamp-extensions",
  "author": {
    "username": "stack72",
    "displayName": "Paul Stack"
  },
  "labels": ["gcp", "google-cloud", "run", "cloud", "infrastructure"],
  "contentTypes": ["models"],
  "contentNames": ["locations", "services", "jobs", "..."],
  "latestVersion": "2026.06.25.1",
  "latestRc": null,
  "latestBeta": null,
  "repositoryVerified": true,
  "repositoryVerifiedAt": "2026-06-25T14:45:56.820Z",
  "repositoryVerifiedUrl": "https://github.com/swamp-club/swamp-extensions",
  "pullCount": 52,
  "score": {
    "percentage": 100,
    "grade": "A"
  },
  "contentMetadata": {
    "models": [
      {
        "fileName": "locations.ts",
        "type": "@swamp/gcp/run/locations",
        "version": "2026.06.08.1",
        "globalArguments": [
          {
            "name": "name",
            "type": "string",
            "description": "Instance name for this resource",
            "required": true
          }
        ],
        "methods": [
          {
            "name": "get",
            "description": "Get a locations",
            "arguments": [
              { "name": "identifier", "type": "string", "required": true }
            ]
          },
          {
            "name": "sync",
            "description": "Sync locations state from GCP",
            "arguments": []
          }
        ]
      }
    ],
    "extensions": [],
    "workflows": [],
    "vaults": [],
    "datastores": [],
    "reports": [],
    "skills": []
  },
  "createdAt": "2026-03-27T23:29:00.394Z",
  "updatedAt": "2026-06-25T14:45:56.820Z"
}

The contentMetadata arrays are empty for content types the extension does not include. The extensions array contains entries for foreign-type grafts — methods the extension adds to types defined by other extensions via export const extension. Each entry lists the target type and the grafted methods:

{
  "contentMetadata": {
    "extensions": [
      {
        "fileName": "custom_sync.ts",
        "targetType": "@acme/base-model",
        "methods": [
          {
            "name": "custom_sync",
            "description": "Sync with a custom backend",
            "arguments": [
              { "name": "endpoint", "type": "string", "required": true }
            ]
          }
        ]
      }
    ]
  }
}

contentMetadata.acceptances holds the acceptances the latest version declared. The key is absent when the version declared none, or when the registry does not return acceptances. Fields the registry sends as null are omitted.

For vault extensions, the vaults array contains entries with configFields instead of methods:

{
  "contentMetadata": {
    "vaults": [
      {
        "fileName": "onepassword.ts",
        "type": "@swamp/1password",
        "name": "1Password",
        "description": "1Password vault provider.",
        "hasConfigSchema": true,
        "configFields": [
          { "name": "op_vault", "type": "string", "required": true },
          { "name": "op_account", "type": "string", "required": false }
        ]
      }
    ]
  }
}

Examples

swamp extension info @swamp/gcp/run
swamp extension info @swamp/gcp/run --json
swamp extension info @swamp/gcp/run --verbose

version

Shows the latest published version of an extension and computes the next CalVer version for today's date. When prerelease versions exist, per-channel latest and next versions are included.

Arguments

[name] — extension name. Required unless --manifest is passed.

Flags

Output

extension·version: Current published: "2026.05.01.1"
extension·version: Next version (today): "2026.05.01.2"

JSON shape

{
  "extensionName": "@swamp/gcp/workstations",
  "currentPublished": "2026.05.01.1",
  "publishedAt": null,
  "nextVersion": "2026.05.01.2"
}

trust

Manage the list of trusted collectives for the repository. Extensions from trusted collectives are installed without a confirmation prompt.

swamp extension trust list

List trusted collectives.

Flags

swamp extension trust add <collective>

Add a collective to the trusted list.

Arguments

Flags

swamp extension trust rm <collective>

Remove a collective from the trusted list.

Arguments

Flags

swamp extension trust auto-trust <enabled>

Enable or disable auto-trusting membership collectives.

Arguments

Flags

source

Manage local extension sources for the repository. Local sources let Swamp discover extensions from directories outside the default extensions/ tree.

swamp extension source list

List configured extension sources.

Flags

swamp extension source add <path>

Add a local extension source.

Arguments

Flags

behaviors is stored as models in .swamp-sources.yaml. An unknown kind fails with Unknown extension kind '<kind>'. Expected one of: models, vaults, datastores, reports, webhooks, workflows (behaviors is accepted for models).

swamp extension source rm <path>

Remove a local extension source.

Arguments

Flags

Cache and registry behavior

Registry lookups performed by list --check-updates and outdated are cached per extension for 24 hours.

• A successful registry response is cached for 24 hours. Subsequent invocations within that window read from the cache rather than the registry.
• A failed registry response (network error, registry unreachable) stamps the entry with latestVersion equal to the installed version and reports it as up to date for the same 24-hour window. The entry continues to read as up to date until the cache expires, even if the registry recovers earlier.
• --no-check-updates on list skips both the cache and the registry.