# Getting Started





<Callout type="warn">
  The CLI is currently in Beta. Commands and flags are still evolving. Make sure you're on the latest version of the CLI if you run into issues.
</Callout>

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.

<YouTubeVideo id="8g-l5kYEGBc" title="Superset CLI + Skills Demo" thumbnail="/images/cli-skills-demo.jpg" />

## Install [#install]

### Desktop app [#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:

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

### Standalone install [#standalone-install]

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

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

### Homebrew [#homebrew]

```bash
brew install superset-sh/tap/superset
```

## Sign in [#sign-in]

```bash
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:

```bash
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`:

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

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

```bash
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 [#verify-your-session]

```bash
superset auth whoami
```

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

## Explore interactively [#explore-interactively]

Bare `superset` in a terminal opens an interactive command browser:
arrow-key through the commands, read their flags, and fill in required
inputs with guided prompts. The confirmation screen shows the exact
command before running it. `superset --help` prints the same catalog as
static, grouped help. Agents and CI always get static help; the browser
never opens there.

<img alt="The interactive command browser" src="__img0" />

## Run your first commands [#run-your-first-commands]

List the projects in your organization:

```bash
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:

```bash
# 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:

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

Then create a workspace against it:

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

Trigger an automation immediately:

```bash
superset automations list
superset automations run aut_…
superset automations logs aut_…
```

## Output modes [#output-modes]

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

| Flag      | Output                                                                                      |
| --------- | ------------------------------------------------------------------------------------------- |
| `--json`  | The data payload as formatted JSON. No envelope.                                            |
| `--quiet` | One ID per line for arrays of objects with `id`; the ID for single objects; JSON otherwise. |

```bash
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 [#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.

```bash
superset hosts list
superset workspaces list              # this machine
superset workspaces list --host h_…  # another host
```

Every host-scoped command targets exactly one host. Reads
(`workspaces list`, `projects list`) default to this machine; mutating
host commands (`projects create`, `projects setup`, `workspaces create`)
require an explicit `--host` or `--local`; there's no default. There is
no org-wide listing; the desktop app is the cross-host view.

## Where state lives [#where-state-lives]

```text
~/.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 [#next-steps]

Continue to the [CLI reference](/cli/cli-reference) for every command,
flag, and output shape.