EXTENSION 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) and governance commands (yank, unyank, 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.

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

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
  }
}

version

Shows the latest published version of an extension and computes the next CalVer version for today's date.

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.