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

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

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

Clear the stored session. 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: "flag" | "env" | "oauth";
}

If a manifest exists and the PID is alive, returns the existing instance's details. Otherwise spawns the host service 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 projects on the target host.

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 on the target host.

Create a workspace on the target host.

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

Delete one or more workspaces on the target host.

superset workspaces delete ws_a ws_b ws_c

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 automations in the active organization.

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

Create an automation. Exactly one of --prompt or --prompt-file 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 to read or replace the prompt body.

Read or replace an automation's prompt body. Without --from-file, prints the current prompt to stdout. With --from-file <path> or piped stdin, replaces the prompt verbatim.

# Read
superset automations prompt aut_… > prompt.md

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

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

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