CLI Reference

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, a new cloud project record is created and the host's main workspace is ensured.

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 that returns the existing mainWorkspaceId.

# 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. Specify exactly one of --branch or --pr. If you pass --agent, you must also pass --prompt. --command runs a one-off shell command in the worktree and is independent of --agent/--prompt. Pass either or both. --effort requires --agent; see the agent effort levels below.

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

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).

superset workspaces update ws_… --name "better-name"
superset workspaces update ws_… --task-id tsk_…
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 --effort high --prompt "Audit the login flow"
superset agents create --workspace ws_… --agent codex --prompt "Review this diff" --attachment ./trace.log

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 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. Provide --prompt or --prompt-file; if both are present, the inline --prompt value is used. At least one of --project or --workspace must be provided, and it must exist on the target host — the CLI verifies this before creating the automation.

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_…