superset

Superset CLI

The superset command provides fast access to spawning subagents and creating copies of projects in isolated workspaces.

If the CLI is not installed, you can install it using curl -fsSL https://superset.sh/cli/install.sh | sh.

Core Workflow

1. Pick a project and host: superset projects list and superset hosts list.
2. Create a Workspace: superset workspaces create --project <id> --host <id> --name "..." --branch <branch> (or --pr <number>, or --local instead of --host).
3. Spawn an agent: superset agents create --workspace <id> --agent claude --prompt "...".
4. Plan work: superset tasks create --title "..." then tasks update <id-or-slug> as work progresses.

Runtime Context

When invoked from inside a Superset workspace or terminal, these environment variables are set and can provide you with context about your session:

• $SUPERSET_WORKSPACE_ID — current workspace id (use directly with agents create --workspace, automations create --workspace, etc.)
• $SUPERSET_TERMINAL_ID — current terminal session id

If $SUPERSET_WORKSPACE_ID is unset, you're not inside a Superset workspace — follow the Core Workflow above to create one.

Workspaces

superset workspaces create --project <id> --host <id> --name "..." --branch <branch>
superset workspaces create --project <id> --local --name "..." --pr <number>
superset workspaces list [--host <id> | --local]
superset workspaces update <id> --name "..."
superset workspaces delete <id> [<id>...]

Provide exactly one of --branch or --pr. With --pr, the host checks out the verified PR head and derives the branch. --base-branch <name> is the fork point when --branch doesn't exist yet.

Optionally act on the new workspace as soon as it's materialized:

superset workspaces create --project <id> --local --name "..." --branch <branch> --agent claude --prompt "fix the build"
superset workspaces create --project <id> --local --name "..." --branch <branch> --agent codex --prompt "review the context" --attachment ./context.md
superset workspaces create --project <id> --local --name "..." --branch <branch> --command "bun install && bun test"

• --agent/--prompt launch an agent in the workspace (both required together) — the inline form of agents create. Repeatable local --attachment <path> values are uploaded first.
• --command <cmd> runs a one-off shell command in the worktree — the inline form of terminals create.

The two are independent — pass either or both. If the workspace is created but its inline agent fails to start, the CLI exits non-zero and prints the retained workspace ID plus an agents create retry.

Agents

superset agents list --host <id>                 # Configured agents on a host (LABEL, PRESET, COMMAND, ID)
superset agents list --local                     # Same, for this machine
superset agents create --workspace <id> --agent claude --prompt "..."

--agent accepts a preset id (e.g. claude, codex), a HostAgentConfig instance UUID, or superset for a built-in Superset chat session. Pass --attachment-id <uuid> once per attachment. Use agents list first if you don't already know which agents are installed on the target host.

agents create --json returns { kind, sessionId, label }. kind is chat (the superset agent) or terminal (e.g. claude, codex) — you need it to build a session deep link (see Opening sessions in the desktop app).

Continue a live terminal agent headlessly with its returned sessionId:

superset agents sessions list [--host <id> | --local] [--workspace <id>]
superset agents sessions read <session-id> --lines 120
superset agents sessions send <session-id> "Now fix the failing test"
superset agents sessions send <session-id> --file follow-up.md --wait --timeout 5m
superset agents sessions wait <session-id> --for idle --timeout 5m

read is a bounded recent terminal snapshot, not a durable transcript. send accepts exactly one source from positional text, --file, or piped stdin. send --wait waits for a post-send idle, permission, failure, or exit event and returns a fresh snapshot when the process remains live. These commands work while the desktop renderer is closed and control terminal agents only; exited process resume and Superset chat sessions are not part of this interface.

Opening sessions in the desktop app

superset workspaces open <id> opens a workspace in the desktop app — it fires the deep link superset://v2-workspace/<id>; add --print to print the URL instead.

superset workspaces open <workspaceId>
superset workspaces open <workspaceId> --print

A session you start with agents create syncs to the desktop app but has no pane in the workspace view until you navigate to it. Recover live terminal IDs with agents sessions list. workspaces open targets only the workspace and cannot focus a session, so build the deep link yourself and append a query param chosen by the session kind:

kind (from agents create --json)	Agents	Deep-link param
chat	superset	?chatSessionId=<sessionId>
terminal	claude, codex	?terminalId=<sessionId>

# chat session (agent: superset)
open "superset://v2-workspace/<workspaceId>?chatSessionId=<sessionId>"

# terminal session (agent: claude, codex, …)
open "superset://v2-workspace/<workspaceId>?terminalId=<sessionId>"

# from inside a workspace, open your own terminal via the env vars
open "superset://v2-workspace/$SUPERSET_WORKSPACE_ID?terminalId=$SUPERSET_TERMINAL_ID"

Add &focusRequestId=<unique> to force a re-focus when opening the same link repeatedly. The session must belong to the workspace in the URL. On Linux/Windows use your platform's URL opener (xdg-open, start) instead of open.

Terminals

superset terminals create --workspace <id> --command "bun test"   # Run a command in a new terminal
superset terminals create --workspace <id>                        # Open an interactive shell

--command is optional — omit it to open a bare shell. --cwd <path> overrides the working directory (defaults to the worktree).

Tasks

superset tasks list                              # List tasks in active org
superset tasks list --priority high --assignee-me
superset tasks get <id-or-slug>
superset tasks create --title "..." [--priority high]
superset tasks update <id-or-slug> --status-id <id>
superset tasks delete <id-or-slug>

Filter flags: --status, --priority, --assignee, --assignee-me (-m), --creator-me, --search (-s), --limit, --offset.

Projects

superset projects list                           # NAME, SLUG, REPO, ID

A project is a checked-out repo. You'll need a project ID to create workspaces or schedule automations.

Hosts

superset hosts list                              # NAME, ONLINE, ID

A host is a registered machine that can run workspaces. Use --local on workspace commands to target this machine.

Automations (alias: auto)

Automations run an agent session on a schedule. Each fire dispatches to a host and produces a workspace you (or a teammate) can open and continue interactively. Two modes:

Provide one or both of --project or --workspace. Schedules are stored as RFC 5545 RRules. Runs are dispatched at-least-once — design prompts to be idempotent. If the target host is offline at fire time, the run is marked skipped_offline and the next occurrence schedules normally. If a workspace is omitted, it will create a fresh clone of a repo for the automation to run in.

superset automations list
superset automations get <id-or-slug>
superset automations create --name "..." --rrule "FREQ=DAILY;BYHOUR=9" \
  --project <id> --agent claude --prompt-file prompt.md
superset automations create --name "..." --rrule "FREQ=WEEKLY;BYDAY=MO" \
  --workspace <id> --agent claude --prompt "Inline prompt"
superset automations update <id> --name "..."
superset automations pause <id>
superset automations resume <id>
superset automations run <id>                    # One-off run
superset automations delete <id>
superset automations logs <id> [--limit N]       # Recent runs
superset automations prompt get <id>             # Print prompt to stdout
superset automations prompt set <id> --from-file prompt.md

prompt get | prompt set round-trips byte-exact, so:

superset automations prompt get <id> > prompt.md
$EDITOR prompt.md
superset automations prompt set <id> --from-file prompt.md

Common Workflows

Run an automation and inspect the result

superset automations list --json | jq '.[] | {id, name}'
superset automations run <id> --json
superset automations get <id> --json

Tips

1. Always use --json when scripting or running as an agent — --json output is consistent per-command.
2. auth whoami before anything else — most failures trace back to an empty organizationId in config or an expired token.

Troubleshooting

• "No active organization": run superset organization list && superset organization switch <id>.
• "Host is offline / error connecting to host": the host's relay tunnel is not connected. Check to make sure both the cli and the target machine are on the latest versions of Superset.