NAMESPACE COMMANDS

The swamp datastore namespace command group manages datastore namespaces. Namespaces scope data within a shared datastore to identify which repository produced it.

All commands accept the standard global options (--json, --log, --log-level, -q, -v, --no-telemetry, --no-color, --show-properties, --repo-dir).

For background on namespaces and shared datastores, see Giga-Swamp and Namespaces.

swamp datastore namespace set

Assign a namespace to this repository.

swamp datastore namespace set <slug>

Arguments

Options

Behavior

Writes the namespace field to the datastore section of .swamp.yaml and registers the namespace in the datastore's namespace manifest. Does not move existing data — run namespace migrate --confirm after setting to reorganize data into the namespaced layout.

If the namespace already exists in the datastore and belongs to a different repository, the command succeeds. Multiple repositories can observe the same namespace in a listing, but only the repository that set it writes data under that namespace.

Example

$ swamp datastore namespace set infra

Namespace set to "infra"
  Datastore: /home/user/my-repo/.swamp

Warning: Existing data remains at the old un-namespaced path.
Run 'swamp datastore namespace migrate --confirm' to move it
to the namespaced layout.

swamp datastore namespace unset

Remove the namespace from this repository.

swamp datastore namespace unset

Options

Behavior

Removes the namespace field from .swamp.yaml. Without --migrate, data remains at its namespaced path. With --migrate --confirm, data is moved from .swamp/<namespace>/... back to .swamp/....

Examples

Unset without data migration:

$ swamp datastore namespace unset

Namespace unset (was "infra")

Unset and reverse-migrate:

$ swamp datastore namespace unset --migrate --confirm

swamp datastore namespace migrate

Migrate data between solo and namespaced directory layouts.

swamp datastore namespace migrate

Options

Behavior

Without --confirm, displays a preview of the migration: each directory to be moved, source and destination paths, file count, and total size. No data is modified.

With --confirm, moves each directory from the solo layout (.swamp/<dir>/) to the namespaced layout (.swamp/<namespace>/<dir>/), or the reverse with --reverse. The catalog is invalidated after migration and rebuilt on the next access.

The directories migrated are: definitions-evaluated, workflows-evaluated, data, outputs, workflow-runs, secrets, vault-bundles, audit, telemetry.

Examples

Preview forward migration:

$ swamp datastore namespace migrate

Migration preview (namespace: "infra")

  definitions-evaluated
    .../.swamp/definitions-evaluated
    → .../.swamp/infra/definitions-evaluated
    12 file(s), 48 KB
  data
    .../.swamp/data
    → .../.swamp/infra/data
    85 file(s), 2.1 MB
  ...

Total: 142 file(s), 3.8 MB

Add --confirm to execute this migration.

Execute forward migration:

$ swamp datastore namespace migrate --confirm

Preview reverse migration:

$ swamp datastore namespace migrate --reverse

Execute reverse migration:

$ swamp datastore namespace migrate --reverse --confirm

swamp datastore namespace list

List all namespaces in the datastore.

swamp datastore namespace list

Options

Output fields

Examples

Table output:

$ swamp datastore namespace list

┌───────────┬──────────────────────────────────────┬──────────────┬─────────┐
│ namespace │ repoId                               │ registeredAt │ current │
├───────────┼──────────────────────────────────────┼──────────────┼─────────┤
│ infra     │ 94735c06-fc0a-4d77-b712-04fbd801b18d │ 2026-05-15   │ *       │
│ compute   │ a2e8f1b3-7c42-4d91-8e56-1f3a5b9c0d2e │ 2026-05-16   │         │
└───────────┴──────────────────────────────────────┴──────────────┴─────────┘

JSON output:

$ swamp datastore namespace list --json

{
  "namespaces": [
    {
      "namespace": "infra",
      "repoId": "94735c06-fc0a-4d77-b712-04fbd801b18d",
      "registeredAt": "2026-05-15T14:30:00.000Z",
      "isCurrent": true
    },
    {
      "namespace": "compute",
      "repoId": "a2e8f1b3-7c42-4d91-8e56-1f3a5b9c0d2e",
      "registeredAt": "2026-05-16T09:15:00.000Z",
      "isCurrent": false
    }
  ],
  "currentNamespace": "infra"
}

swamp datastore catalog pull

Pull catalog metadata from foreign namespaces.

swamp datastore catalog pull --namespaces <namespaces>

Options

Behavior

Fetches catalog entries (model names, types, data output names, version counts) from the specified foreign namespaces into the local catalog cache. The pulled metadata is read-only and has no automatic refresh or TTL.

Example

$ swamp datastore catalog pull --namespaces infra,security

Related

• Giga-Swamp and Namespaces — why namespaces exist and how they work
• Giga-Swamp How-to Guides — step-by-step namespace operations
• Datastore Configuration — namespace field in .swamp.yaml
• CEL Expressions — cross-namespace query syntax