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

{
  pid: number;
  port: number;
  organizationId: string;
}

Sends SIGTERM, waits up to 10 seconds, sends SIGKILL if still alive. The manifest is removed in all cases — including when SIGTERM itself throws.

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 }

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

// Running
{
  running: true;
  healthy: boolean;
  pid: number;
  port: number;
  endpoint: string;
  organizationId: 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 in the active organization. Org-wide; not host-scoped.

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

List workspaces accessible to the active organization. With neither --host nor --local, the list is organization-wide.

Create a workspace on the target host. Specify exactly one of --branch or --pr. If you pass --agent, you must also pass --prompt.

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.

superset workspaces delete ws_a ws_b ws_c

Update a workspace.

superset workspaces update ws_… --name "better-name"

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

Launch an agent inside an existing workspace. Resolves the host that owns the workspace and starts the named preset (or HostAgentConfig instance) in a fresh terminal session on that host.

superset agents run --workspace ws_… --agent claude --prompt "Audit the login flow"
superset agents run --workspace ws_… --agent codex --prompt "Review this diff" --attachment ./trace.log

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.

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