WORKSPACE COMMANDS

A workspace is a Swamp repo that Swamp keeps track of in the workspace registry. A workspace is still an ordinary repo: every other command works in it unchanged.

There are two kinds of workspace:

The registry is <config dir>/workspaces.json. The data dir is ~/.swamp by default. Both move with SWAMP_HOME, and the config dir also moves with SWAMP_CONFIG_DIR.

swamp start and swamp workspace share the registry and the folders. A workspace created or imported by either one is listed by the other, and swamp start status lists the same workspaces. See Start a task with swamp start.

Running swamp workspace with no subcommand prints group help. Every subcommand accepts --json.

swamp workspace create <name>

Create a Swamp repo under <data dir>/workspaces/<name> and register it. No agent is set up in it.

swamp workspace create <name>

$ swamp workspace create infra
✓ Created workspace infra: /Users/alice/.swamp/workspaces/infra

With --json:

{
  "name": "infra",
  "path": "/Users/alice/.swamp/workspaces/infra"
}

For folder_exists, the message gives the import command that registers the folder:

Error: A workspace folder is already at /Users/alice/.swamp/workspaces/infra, but it isn't registered. Bring it back with: swamp workspace import "/Users/alice/.swamp/workspaces/infra". Or delete the folder first.

swamp workspace import <path>

Register an existing Swamp repo as a workspace, where it is. Nothing is moved or copied.

swamp workspace import <path> [--name <name>]

The default name is the folder name lowercased, with other characters turned into dashes. If that name is registered, -2, -3 and so on is added: a folder named My_Infra imports as my-infra, or my-infra-2 when my-infra is taken.

$ swamp workspace import ~/code/My_Infra
✓ Imported workspace my-infra-2: /Users/alice/code/My_Infra

Importing a folder that is already registered succeeds, and reports the name it is registered under. --name is ignored in that case.

$ swamp workspace import ~/code/My_Infra
• /Users/alice/code/My_Infra is already the workspace my-infra-2

With --json, alreadyRegistered is true only for a folder that was already registered:

{
  "name": "my-infra-2",
  "path": "/Users/alice/code/My_Infra",
  "alreadyRegistered": true
}

swamp workspace list

List every registered workspace by name and folder. Writes nothing.

swamp workspace list

An imported workspace is marked imported. A folder that is gone, or that is no longer a Swamp repo, is marked as well:

$ swamp workspace list
infra       /Users/alice/.swamp/workspaces/infra
my-infra-2  /Users/alice/code/My_Infra (imported, folder missing)
scratch     /Users/alice/code/scratch (imported, not a swamp folder)

With --json, folder is ok, missing or not_a_repo:

{
  "workspaces": [
    {
      "name": "infra",
      "path": "/Users/alice/.swamp/workspaces/infra",
      "createdAt": "2026-10-14T03:26:16.561Z",
      "imported": false,
      "folder": "ok"
    },
    {
      "name": "my-infra-2",
      "path": "/Users/alice/code/My_Infra",
      "createdAt": "2026-10-14T03:26:05.765Z",
      "imported": true,
      "folder": "missing"
    }
  ]
}

swamp workspace get <name>

Show one workspace. Writes nothing.

swamp workspace get <name>

$ swamp workspace get my-infra-2
Name: my-infra-2
Path: /Users/alice/code/My_Infra
Created: 2026-10-14T03:26:05.765Z
Imported: yes
Trusted: no
Agents: claude

An unknown name fails with not_found:

Error: No workspace named "prod". Run 'swamp workspace list' to see them.

swamp workspace remove <name>

Take a workspace off the registry and drop the agent trust recorded for its folder. The folder is never deleted.

swamp workspace remove <name>

The output gives the command that brings the workspace back:

$ swamp workspace remove infra
✓ Removed workspace infra
  Its folder is still at /Users/alice/.swamp/workspaces/infra
  Bring it back with: swamp workspace import "/Users/alice/.swamp/workspaces/infra"

After importing it again, agent trust has to be confirmed again. A workspace that a running swamp start has open is removed as well, and the output says so; with --json, openInStart reports it.

swamp start --workspace <name> re-registers a removed workspace's folder under <data dir>/workspaces/<name> without saying so, where swamp workspace create refuses it with folder_exists.

Workspaces from earlier swamp start

Folders that swamp start created under <data dir>/workspaces/ before the registry existed are adopted the first time a command writes the registry. swamp workspace list and swamp workspace get report them without writing anything.