Superset

---
name: superset
description: Create workspaces, spawn agents, schedule automations, and manage Superset projects/tasks/hosts via the `superset` CLI. Use to orchestrate coding agents across devices from the terminal.
allowed-tools: Bash(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 fire dispatches to a host and produces a workspace you (or a teammate) can open and continue interactively. Two modes:

Provide one or both of `--project` or `--workspace`. Schedules are stored as [RFC 5545 RRules](https://datatracker.ietf.org/doc/html/rfc5545#section-3.8.5). Runs are dispatched at-least-once — design prompts to be idempotent. If the target host is offline at fire time, the run is marked `skipped_offline` and the next occurrence schedules normally. 
If a workspace is omitted, it will create a fresh clone of a repo for the automation to run in.

```bash
superset automations list
superset automations get <id-or-slug>
superset automations create --name "..." --rrule "FREQ=DAILY;BYHOUR=9" \
  --project <id> --agent claude --prompt-file prompt.md
superset automations create --name "..." --rrule "FREQ=WEEKLY;BYDAY=MO" \
  --workspace <id> --agent claude --prompt "Inline prompt"
superset automations update <id> --name "..."
superset automations pause <id>
superset automations resume <id>
superset automations run <id>                    # One-off run
superset automations delete <id>
superset automations logs <id> [--limit N]       # Recent runs
superset automations prompt get <id>             # Print prompt to stdout
superset automations prompt set <id> --from-file prompt.md
```

`prompt get | prompt set` round-trips byte-exact, so:

```bash
superset automations prompt get <id> > prompt.md
$EDITOR prompt.md
superset automations prompt set <id> --from-file prompt.md
```

## Common Workflows

### Run an automation and inspect the result

```bash
superset automations list --json | jq '.[] | {id, name}'
superset automations run <id> --json
superset automations get <id> --json
```

## Tips

1. **Always use `--json`** when scripting or running as an agent — `--json` output is consistent per-command.
2. **`auth whoami` before anything else** — most failures trace back to an empty `organizationId` in config or an expired token.

## Troubleshooting

- **"No active organization"**: run `superset organization list && superset organization switch <id>`.
- **"Host is offline / error connecting to host"**: the host's relay tunnel is not connected. Check to make sure both the cli and the target machine are on the latest versions of Superset.