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, trust, source) are not covered here.

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.

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)"

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",
        "..."
      ]
    }
  ]
}

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.

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. Explicit version pinning (@name@version) ignores --channel. The lockfile records the installed channel so that subsequent update checks stay within it.

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>/.

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"
}
{
  "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.

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.

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 --force:

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

With --force:

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 (model 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: Models (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 model extensions, Vaults for vault extensions, and so on. Extensions that bundle multiple content types show one section per type.

Output (with --verbose)

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

extension·info: Models (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": []
          }
        ]
      }
    ],
    "workflows": [],
    "vaults": [],
    "drivers": [],
    "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. 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"
}

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.