Getting Started

The Superset CLI (superset) is a single static binary that drives the same backend as the desktop app. Use it to manage workspaces, tasks, automations, and the local host server from your terminal or from CI.

Install

Desktop app

The desktop app includes the Superset CLI. When the app launches, it writes an app-managed shim at ~/.superset/bin/superset, and Superset terminals prepend ~/.superset/bin to PATH automatically.

To use the bundled CLI from a normal shell, add the directory to your shell profile:

export PATH="$HOME/.superset/bin:$PATH"

Standalone install

curl -fsSL https://superset.sh/cli/install.sh | sh

The script auto-detects your platform (macOS Apple Silicon or Linux x86_64), installs Superset under ~/superset by default, and adds ~/superset/bin to your shell PATH.

Homebrew

brew install superset-sh/tap/superset

Sign in

superset auth login

The CLI starts a loopback callback server on 127.0.0.1:51789 (or 51790 through 51793 if earlier ports are busy), opens your browser to the consent page, and stores a session token at ~/.superset/config.json.

If you belong to multiple organizations, you'll be prompted to pick one. To skip the prompt and pick directly:

superset auth login --organization acme

For CI or other non-interactive environments — where there's no browser to complete the OAuth flow — use an API key instead. You can either store it once with auth login --api-key:

superset auth login --api-key sk_live_…
superset auth whoami

…or set SUPERSET_API_KEY per-invocation without writing anything to disk:

export SUPERSET_API_KEY=sk_live_…
superset auth whoami

API keys are issued from the Settings → API Keys page in the desktop app.

Verify your session

superset auth whoami

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

Run your first commands

List the projects in your organization:

superset projects list

If your repo isn't there yet, register it on this machine — clone from a Git URL or import an existing checkout:

# Clone from a URL
superset projects create --name "my-app" --local \
  --clone https://github.com/org/my-app.git \
  --parent-dir ~/code

# Or register an existing local checkout
superset projects create --name "my-app" --local --import ~/code/my-app

If the project already exists in your org but isn't on this machine, attach to it instead of creating a duplicate:

superset projects setup <id-from-projects-list> --local --parent-dir ~/code

Then create a workspace against it:

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

Trigger an automation immediately:

superset automations list
superset automations run aut_…
superset automations logs aut_…

Output modes

Every command prints a TTY-friendly view by default. Two flags switch the shape of the output for scripting:

superset tasks list --status in_progress --json | jq '.[].title'
superset workspaces list --quiet | xargs -L1 superset workspaces delete

When the CLI detects an agent or CI environment (CLAUDE_CODE, CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, CODEX_CLI, GEMINI_CLI, SUPERSET_AGENT, or CI set to a non-empty value), it defaults to JSON output unless you pass --quiet.

Local vs. remote hosts

Commands that touch a host accept --host <id> to pick which host handles the request, or --local for this machine. Local-targeted calls go straight to the host server over loopback (offline-friendly); remote calls route through the cloud API and the relay.

superset hosts list
superset workspaces list
superset workspaces list --host h_…
superset workspaces list --local

Mutating host commands (projects create, projects setup, workspaces create) require an explicit --host or --local — there's no default. workspaces list is organization-wide when neither --host nor --local is provided; pass --local to restrict it to this machine.

Where state lives

~/.superset/config.json                            # auth, active organization
~/.superset/host/<organizationId>/manifest.json    # host server endpoint + token
~/.superset/host/<organizationId>/host.db          # local host server DB

SUPERSET_HOME_DIR relocates the whole tree, matching the desktop app.

Next steps

Continue to the CLI reference for every command, flag, and output shape.