superset

# Superset CLI

The `superset` command provides fast access to spawning subagents and creating copies of projects in isolated workspaces.

If the CLI is not installed, you can install it using `curl -fsSL https://superset.sh/cli/install.sh | sh`.

## Core Workflow

1. **Pick a project and host**: `superset projects list` and `superset hosts list`.
2. **Create a Workspace**: `superset workspaces create --project <id> --host <id> --name "..." --branch <branch>` (or `--pr <number>`, or `--local` instead of `--host`).
3. **Spawn an agent**: `superset agents create --workspace <id> --agent claude --prompt "..."`.
4. **Plan work**: `superset tasks create --title "..."` then `tasks update <id-or-slug>` as work progresses.

## Runtime Context

When invoked from inside a Superset workspace or terminal, these environment variables are set and can provide you with context about your session:

- `$SUPERSET_WORKSPACE_ID` — current workspace id (use directly with `agents create --workspace`, `automations create --workspace`, etc.)
- `$SUPERSET_TERMINAL_ID` — current terminal session id

If `$SUPERSET_WORKSPACE_ID` is unset, you're not inside a Superset workspace — follow the Core Workflow above to create one.

## Workspaces

```bash
superset workspaces create --project <id> --host <id> --name "..." --branch <branch>
superset workspaces create --project <id> --local --name "..." --pr <number>
superset workspaces list [--host <id> | --local]
superset workspaces update <id> --name "..."
superset workspaces delete <id> [<id>...]
```

Provide exactly one of `--branch` or `--pr`. With `--pr`, the host checks out the verified PR head and derives the branch. `--base-branch <name>` is the fork point when `--branch` doesn't exist yet.

Optionally act on the new workspace as soon as it's materialized:

```bash
superset workspaces create --project <id> --local --name "..." --branch <branch> --agent claude --prompt "fix the build"
superset workspaces create --project <id> --local --name "..." --branch <branch> --command "bun install && bun test"
```

- `--agent`/`--prompt` launch an agent in the workspace (both required together) — the inline form of `agents create`.
- `--command <cmd>` runs a one-off shell command in the worktree — the inline form of `terminals create`.

The two are independent — pass either or both.

## Agents

```bash
superset agents list --host <id>                 # Configured agents on a host (LABEL, PRESET, COMMAND, ID)
superset agents list --local                     # Same, for this machine
superset agents create --workspace <id> --agent claude --prompt "..."
```

`--agent` accepts a preset id (e.g. `claude`, `codex`), a HostAgentConfig instance UUID, or `superset` for a built-in Superset chat session. Pass `--attachment-id <uuid>` once per attachment. Use `agents list` first if you don't already know which agents are installed on the target host.

`agents run --json` returns `{ kind, sessionId, label }`. `kind` is `chat` (the `superset` agent) or `terminal` (e.g. `claude`, `codex`) — you need it to build a session deep link (see [Opening sessions in the desktop app](#opening-sessions-in-the-desktop-app)).

## Opening sessions in the desktop app

`superset workspaces open <id>` opens a **workspace** in the desktop app — it fires the deep link `superset://v2-workspace/<id>`; add `--print` to print the URL instead.

```bash
superset workspaces open <workspaceId>
superset workspaces open <workspaceId> --print
```

A session you start with `agents run` syncs to the desktop app but has **no pane** in the workspace view until you navigate to it, and there is no session list — so a freshly created session is effectively invisible until opened. `workspaces open` targets only the workspace and cannot focus a session, so build the deep link yourself and append a query param chosen by the session `kind`:

| `kind` (from `agents run --json`) | Agents | Deep-link param |
| --- | --- | --- |
| `chat` | `superset` | `?chatSessionId=<sessionId>` |
| `terminal` | `claude`, `codex` | `?terminalId=<sessionId>` |

```bash
# chat session (agent: superset)
open "superset://v2-workspace/<workspaceId>?chatSessionId=<sessionId>"

# terminal session (agent: claude, codex, …)
open "superset://v2-workspace/<workspaceId>?terminalId=<sessionId>"

# from inside a workspace, open your own terminal via the env vars
open "superset://v2-workspace/$SUPERSET_WORKSPACE_ID?terminalId=$SUPERSET_TERMINAL_ID"
```

Add `&focusRequestId=<unique>` to force a re-focus when opening the same link repeatedly. The session must belong to the workspace in the URL. On Linux/Windows use your platform's URL opener (`xdg-open`, `start`) instead of `open`.

## Terminals

```bash
superset terminals create --workspace <id> --command "bun test"   # Run a command in a new terminal
superset terminals create --workspace <id>                        # Open an interactive shell
```

`--command` is optional — omit it to open a bare shell. `--cwd <path>` overrides the working directory (defaults to the worktree).

## Tasks

```bash
superset tasks list                              # List tasks in active org
superset tasks list --priority high --assignee-me
superset tasks get <id-or-slug>
superset tasks create --title "..." [--priority high]
superset tasks update <id-or-slug> --status-id <id>
superset tasks delete <id-or-slug>
```

Filter flags: `--status`, `--priority`, `--assignee`, `--assignee-me` (`-m`), `--creator-me`, `--search` (`-s`), `--limit`, `--offset`.

## Projects

```bash
superset projects list                           # NAME, SLUG, REPO, ID
```

A project is a checked-out repo. You'll need a project ID to create workspaces or schedule automations.

## Hosts

```bash
superset hosts list                              # NAME, ONLINE, ID
```

A host is a registered machine that can run workspaces. Use `--local` on workspace commands to target this machine.

## Automations (alias: `auto`)

Automations run an agent session on a schedule. Each fir