Superset CLI Reference

Add a terminal script to the desktop app on this machine. The desktop app must have been launched once so its local database exists, and the CLI must have an active organization so the script is imported into the correct v2 profile. When iterating on one script, pass --upsert so each revision replaces the last instead of piling up copies in the Scripts bar.

superset scripts add --name dev --command "bun run dev"
superset presets add --name services \
  --command "docker compose up" --command "bun run dev" \
  --execution-mode split-pane
superset scripts add --name "Open in GitHub" --command "gh pr view --web" --upsert

List the terminal scripts on this machine with the id each other command takes. status is importing or deleting while a change is waiting for the desktop app to open or refocus with the same organization active. Scripts created in the desktop app's Settings are stored in the app profile only and do not appear here.

superset scripts list
superset scripts list --json

Change fields on an existing script. Unspecified fields keep their values, and the desktop app updates its copy in place, so the script keeps its position in the Scripts bar. Edits made in the desktop app's Settings do not flow back to the CLI: an edit here replaces the app's copy with what superset scripts list shows plus your changes.

superset scripts edit <id> --command "gh pr view --web"
superset scripts edit <id> --name "Open PR" --hidden
superset scripts edit <id> --all-projects --no-hidden

Delete a script. The desktop app removes its copy the next time it opens or refocuses with the same organization active (immediately when it is running); until then the script lists with status deleting.

superset scripts delete <id>

Authenticate via browser OAuth and store a session token at ~/.superset/config.json.

Single-org accounts are selected automatically. With multiple orgs and a TTY, the CLI prompts; with multiple orgs and no TTY, you must pass --organization or the command exits 1 listing the available slugs.

superset auth login
superset auth login --organization acme

To sign in with an API key (useful for CI or any environment where the OAuth browser flow isn't an option), pass --api-key. The CLI validates the key, stores it at ~/.superset/config.json, and clears any prior OAuth session.

superset auth login --api-key sk_live_…
superset auth login --api-key sk_live_… --organization acme

◇  Authorized!
│  Satya Patel (you@example.com)
│  Organization: Acme
└  Logged in successfully.

{
  userId: string;
  organizationId: string;
  organizationName: string;
}

Clear stored credentials: both an OAuth session and a stored API key. Does not call the API and does not clear the active organization (your preferred org persists across re-logins).

superset auth logout

Logged out.

{ message: "Logged out." }

Show the current user, active organization, and auth source.

superset auth whoami

Signed in as Satya Patel (you@example.com)
Organization: Acme
Auth: Session (expires in 32 min)

{
  userId: string;
  email: string;
  name: string;
  organizationId: string;
  organizationName: string;
  authSource: "override" | "config" | "oauth";
}

If a manifest exists and the PID is alive, returns the existing instance's { pid, endpoint }. Otherwise spawns the host server binary, polls /trpc/health.check for up to 10 seconds, and writes the manifest. Binds to 127.0.0.1 only.

superset start --daemon

// Freshly started
{
  pid: number;
  port: number;
  organizationId: string;
}

// Already running
{
  pid: number;
  endpoint: string;
}

Sends SIGTERM, waits up to 10 seconds, sends SIGKILL if still alive, then removes the manifest. If sending SIGTERM itself throws, the command errors and the manifest is left in place.

superset stop

// No manifest
{ running: false }

// Manifest existed
{ pid: number; organizationId: string }

healthy reflects a live health.check request (2-second timeout).

superset status

// No manifest
{ running: false; organizationId: string; hostId: string }

// Manifest exists but PID is dead
{
  running: false;
  stale: true;
  pid: number;
  organizationId: string;
  hostId: string;
}

// Running
{
  running: true;
  healthy: boolean;
  pid: number;
  port: number;
  endpoint: string;
  organizationId: string;
  hostId: string;
  hostName: string;
  uptimeSec: number;
}

Downloads the matching superset-<platform>.tar.gz from GitHub Releases and atomically replaces the install root. Only available in built binaries; running from bun run dev errors out.

superset update                     # upgrade to the latest release
superset update --check             # show current → target without installing
superset update --version 0.1.2     # install a specific version (up or down)

Updated 0.1.4 → 0.1.5 (/Users/you/.local/share/superset)

// --check
{
  current: string;
  target: string;
  upToDate: boolean;
  pinned: boolean;
}

// install
{
  current: string;
  target: string;
  updated: boolean;
  installRoot?: string;
}

List organizations available to the current auth context. Marks the active one.

Set the active organization in ~/.superset/config.json.

superset organization switch acme
superset org switch org_…

List members in the active organization.

superset organization members list
superset org members list -s satya

List projects on a host. Defaults to this machine; pass --host <id> for another host.

Create a fresh project on a host. Two modes:

• Clone: pass --clone <url> and --parent-dir. The host clones the repo into <parent-dir>/<derived-name>/.
• Import: pass --import <path> to register a repo that already exists on disk.

Either way, the project is registered on the host with no workspaces yet; create one with superset ws create --project <id> --name local --checkout local --local (the repo's checkout as it is) or --branch <name> (its own worktree).

create always creates a new cloud project, even if your org already has one for the same Git URL. Use projects setup when adopting an existing project on a fresh machine.

superset projects create --name "my-app" --local --clone https://github.com/org/my-app.git --parent-dir ~/code
superset projects create --name "my-app" --local --import ~/code/my-app

Adopt an existing project onto a host without creating a duplicate cloud record. Counterpart to create for the "new machine, repo already in the org" case.

Find the project ID via projects list.

Idempotent: re-running against a project that's already set up at the same path is a no-op.

# Pick an ID from `superset projects list`, then clone it onto this machine
superset projects setup 47c31b04-… --local --parent-dir ~/code

# Or register an existing local checkout
superset projects setup 47c31b04-… --local --import ~/code/my-app

List hosts registered to the active organization. Host registration happens via superset start on each machine. There is no separate registration command.

superset hosts list

Set (or clear) the command used to wake a host.

superset hosts set-wake my-sandbox vercel sandbox resume my-box
superset hosts set-wake my-sandbox --clear

Wake a host by running its configured wake command locally, streaming its output.

superset hosts wake my-sandbox

List workspaces on a host. Defaults to this machine; pass --host <id> for another host. Workspaces are host-owned; there is no org-wide listing (the desktop app is the cross-host view). projectName falls back to the raw project id when the host doesn't know the project's name.

Create a workspace on the target host. With --project, specify one of --checkout local, --branch, --pr, or --task (--branch and --pr are mutually exclusive). If you pass --agent, you must also pass --prompt. --command runs a one-off shell command in the workspace directory and is independent of --agent/--prompt. Pass either or both. --model and --effort require --agent; see the agent effort levels below.

--checkout local shares the project's existing files, git index and checked-out branch. It does not switch branches or run setup. Do not combine it with --branch, --pr, --base-branch, or --skip-branch-prefix. Local creation requires a host that supports local workspaces; older hosts reject it without creating a worktree. --local selects this machine and is independent of --checkout local.

Pass --session explicitly to create a session: a project-less workspace backed by a managed folder under ~/.superset/sessions, initialized as its own git repo. Sessions have no branch semantics, so --branch, --pr, --task, --base-branch, --checkout, --skip-branch-prefix, and --tag are rejected, --name is optional, and the output has no alreadyExists field. Host workspace creation requires either --project <id> or --session; omitting both is an error.

superset workspaces create \
  --project prj_… \
  --name "fix-login-bug" \
  --branch fix/login-bug \
  --local

superset workspaces create \
  --project prj_… \
  --name "review-pr-123" \
  --pr 123 \
  --local

# Project-less session with an agent
superset workspaces create --session --local --agent claude --prompt "…"

# Tags group the workspace into sidebar folders — no folder setup needed
superset workspaces create --project prj_… --name "perf-spike" --branch perf/spike --local --tag perf

Delete one or more workspaces on the target host (default: this machine).

superset workspaces delete ws_a ws_b ws_c

Show details for a single workspace on its host. --field is handy in scripts: superset workspaces get --field worktreePath.

superset workspaces get ws_…
superset workspaces get --field branch   # inside a workspace

Update a workspace on its host (default: this machine). --tag replaces the whole tag set — tagging is how workspaces group into sidebar folders, so retagging moves the workspace between folders.

superset workspaces update ws_… --name "better-name"
superset workspaces update ws_… --task-id tsk_…
superset workspaces update ws_… --tag perf --tag infra
superset workspaces update ws_… --clear-task

Open a workspace in the Superset desktop app.

superset workspaces open ws_…
superset workspaces open ws_… --print

List agents configured on a host. First call on a fresh host seeds the bundled defaults.

superset agents list --local
superset agents list --host host_…

Create an agent session in an existing workspace on its host (default: this machine): starts the named preset (or HostAgentConfig instance) in a fresh terminal session there.

superset agents create --workspace ws_… --agent claude --model sonnet --effort high --prompt "Audit the login flow"
superset agents create --workspace ws_… --agent codex --prompt "Review this diff" --attachment ./trace.log
# Restore a killed agent session by the agent's own session id
superset agents create --workspace ws_… --agent claude --resume-session 0b7c…

Agent models

Model is an explicit override for one launch. If you omit --model, Superset passes no model flag and the agent uses its own configured default. Ids match the desktop model picker: Claude takes a family alias (fable, opus, sonnet, haiku) that tracks the newest release, or a pinned id such as claude-opus-4-8. The host rejects an unknown id before launching the agent, and the error names every id that agent accepts. Agents without a model picker, including Superset chat, reject an explicit model override.

Agent effort levels

Effort is an explicit override for one launch. If you omit --effort, Superset passes no effort flag and the agent uses its own configured default. The host rejects unsupported values before launching the agent.

Other agents, including Superset chat, currently use their own default and reject an explicit effort override.

Create a terminal session in an existing workspace on its host (default: this machine): opens a fresh PTY in the worktree, optionally running a command.

superset terminals create --workspace ws_… --command "bun install && bun test"
superset terminals create --workspace ws_…

List the live terminal sessions in a workspace. Presence in the list means the PTY exists, not that an agent inside it is working or idle.

Read a terminal's current screen back as text without mutating the session.

superset terminals read --workspace ws_… --terminal term_… --max-lines 240

Send a follow-up message to a terminal already running in a workspace, e.g. to give an agent new instructions mid-session.

Close (dispose) a terminal running in a workspace. This ends the session.

List the browser panes open in a workspace.

Open a URL in a browser pane and return its paneId. Requires the workspace to be visible in the desktop app (the renderer creates the pane).

superset browser open --workspace ws_… --url http://localhost:3000 --target new-tab

Point an existing pane at a new URL. file://, chrome://, and custom schemes are refused.

Capture a PNG screenshot of the pane's page.

Evaluate JavaScript in the page and return the result — the ergonomic path for reading or nudging the DOM.

superset browser eval --workspace ws_… --pane pane_… \
  --code "document.querySelector('h1')?.textContent"

Read the pane's captured console output.

Print a raw Chrome DevTools Protocol WebSocket endpoint for the pane, for browser-use / Playwright-class tools (mouse, keyboard, scroll, DOM, network). The URL embeds an auth token — treat it as a secret.

List tasks in the active organization.

superset tasks list --assignee-me
superset t list -s "auth" --json

Get a task by ID or slug.

superset tasks get tsk_…
superset tasks get fix-login-bug

Create a task.

superset tasks create --title "Audit auth flow" --priority high

Update a task. Same fields as create, all optional.

superset tasks update fix-login-bug --priority urgent

Delete one or more tasks.

superset tasks delete tsk_a tsk_b

List task statuses in the active organization. Use the returned IDs with tasks list --status, tasks create --status-id, or tasks update --status-id.

superset tasks statuses list

List automations in the active organization.

Get an automation's metadata. The prompt body is omitted. Use automations prompt get to read it. Use automations logs for run history.

Create an automation. Automations are a Pro feature: create, run, and resume need a Pro or Enterprise subscription on the active organization and fail with Automations require the Pro plan. otherwise. Provide --prompt or --prompt-file; if both are present, the inline --prompt value is used. A --project or --workspace must exist on the target host; the CLI verifies this before creating the automation. Omit both for session mode: each run creates a project-less session workspace on the target host.

Every run's created workspace carries the automation's tags, which group it into the matching sidebar folders. By default automations are tagged automation, so their runs collect in an automation folder per project; pass --tag to file runs elsewhere.

superset automations create \
  --name "Weekday triage" \
  --project prj_… \
  --workspace ws_… \
  --rrule "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0" \
  --prompt-file ./prompts/triage.md

Update an automation's metadata (name, schedule, agent, host). All flags optional. Omitting a flag preserves the existing value: undefined means "no change", not "clear". Use automations prompt get or automations prompt set to read or replace the prompt body.

Print an automation's prompt body to stdout. The output is the raw prompt with no trailing newline added, so prompt get and prompt set round-trip byte-exactly.

# Read to a file
superset automations prompt get aut_… > prompt.md

# Verify a push landed
superset automations prompt get aut_… | diff - ./prompt.md

Replace an automation's prompt body. The new prompt fully overwrites the old one.

# Write from file
superset automations prompt set aut_… --from-file ./prompt.md

# Write from stdin
cat ./prompt.md | superset automations prompt set aut_… --from-file -

Delete an automation.

superset automations delete aut_…

Pause an automation (sets enabled: false).

superset automations pause aut_…

Resume an automation (sets enabled: true). The API recomputes nextRunAt on resume.

superset automations resume aut_…

Dispatch an automation immediately. Does not wait for completion.

superset automations run aut_…

List recent runs for an automation.

superset automations logs aut_…

List every settable key with its current value, default, and allowed values. isSet: false means the app is using its built-in default.

superset settings list

Print the effective value of one setting (falls back to the app default when unset).

superset settings get terminalFontSize

Set a setting. Booleans accept true/false/on/off/1/0/yes/no; enums and numeric ranges are validated the same way the desktop settings UI validates them.

superset settings set confirmOnQuit false
superset settings set terminalFontSize 16
superset settings set defaultEditor cursor
superset settings set selectedRingtoneId ping

Reset a setting to the app default.

superset settings reset terminalFontSize

List available themes: system (follows OS appearance), the built-ins (dark, light, monokai, catppuccin-latte, solarized-light, vellum), and any custom themes imported through the app.

superset settings theme list

Print the active theme.

superset settings theme get

Export a theme's full JSON definition, the starting point for creating a custom theme: export a built-in, edit the colors, then import it.

superset settings theme export dark --out my-theme.json

Import custom themes, using the same validation and normalization as the desktop's Appearance UI (ids are slugified; missing colors are filled from the built-in base theme; reserved ids like dark are rejected). Re-importing an id replaces that custom theme.

superset settings theme export dark --out my-theme.json
# edit my-theme.json (id, name, ui/terminal/editor colors)
superset settings theme import my-theme.json
superset settings theme set my-theme

Remove a custom theme. If it was the active theme (or a system light/dark mapping), that reference falls back to the default.

superset settings theme remove my-theme

Set the active theme and/or the system light/dark mappings. A running desktop app restyles live; without one the theme applies on next launch. (On app versions without live reload, quit the app first, then set, then relaunch, or the app may overwrite the change.)

superset settings theme set monokai
superset settings theme set system --system-light light --system-dark monokai