Paradev CLI Reference

Add a terminal script to the desktop app on this machine. The desktop app must have been launched once so its local database exists, and the CLI must have an active organization so the script is imported into the correct v2 profile. Pass --upsert when iterating so each revision replaces the last.

superset scripts add --name dev --command "bun run dev"
superset presets add --name services \
  --command "docker compose up" --command "bun run dev" \
  --execution-mode split-pane
superset scripts add --name "Open in GitHub" --command "gh pr view --web" --upsert

List the terminal scripts on this machine with the id each other command takes. status is importing or deleting while a change is waiting for the desktop app to open or refocus with the same organization active. Scripts created in the desktop app's Settings are stored in the app profile only and do not appear here.

superset scripts list
superset scripts list --json

Change fields on an existing script. Unspecified fields keep their values, and the desktop app updates its copy in place, so the script keeps its position in the Scripts bar. Edits made in the desktop app's Settings do not flow back to the CLI: an edit here replaces the app's copy with what superset scripts list shows plus your changes.

superset scripts edit <id> --command "gh pr view --web"
superset scripts edit <id> --name "Open PR" --hidden
superset scripts edit <id> --all-projects --no-hidden

Delete a script. The desktop app removes its copy the next time it opens or refocuses with the same organization active (immediately when it is running); until then the script lists with status deleting.

superset scripts delete <id>

Authenticate via browser OAuth and store a session token at ~/.paradev/config.json.

Single-org accounts are selected automatically. With multiple orgs, the CLI prompts on a TTY. Without a TTY, pass --organization or the command exits 1 and lists the available slugs.

superset auth login
superset auth login --organization acme

To sign in with an API key (for CI or any place without a browser), pass --api-key. The CLI validates the key, stores it at ~/.paradev/config.json, and clears any prior OAuth session.

superset auth login --api-key sk_live_…
superset auth login --api-key sk_live_… --organization acme

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

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

Clear stored credentials: both an OAuth session and a stored API key. 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: "override" | "config" | "oauth";
}

If a manifest exists and the PID is alive, returns the existing instance's { pid, endpoint }. Otherwise spawns the host server binary, polls /trpc/health.check for up to 10 seconds, and writes the manifest. Binds to 127.0.0.1 only.

superset start --daemon

// Freshly started
{
  pid: number;
  port: number;
  organizationId: string;
}

// Already running
{
  pid: number;
  endpoint: string;
}

Sends SIGTERM, waits up to 10 seconds, sends SIGKILL if still alive, then removes the manifest. If sending SIGTERM itself throws, the command errors and the manifest is left in place.

The terminal daemon keeps running after the host server stops, so the next superset start picks up the same terminals. With --terminals, the command stops the host server first, then the terminal daemon. It signals only the pid the daemon reports over its socket, never the pid in its manifest, which can be stale. If the socket is missing or refuses the connection, the manifest is removed without a signal. If the socket accepts the connection but the daemon does not answer, the command errors after it stops the host server and leaves the daemon and its manifest in place.

superset stop
superset stop --terminals

// Nothing running
{ running: false }

// Something stopped
{
  pid: number | null;               // host server; null if none was running
  terminalDaemonPids: number[];     // empty without --terminals or if none was running
  organizationId: string;
}

healthy reflects a live health.check request (2-second timeout).

superset status

// No manifest
{ running: false; organizationId: string; hostId: string }

// Manifest exists but PID is dead
{
  running: false;
  stale: true;
  pid: number;
  organizationId: string;
  hostId: string;
}

// Running
{
  running: true;
  healthy: boolean;
  pid: number;
  port: number;
  endpoint: string;
  organizationId: string;
  hostId: string;
  hostName: string;
  uptimeSec: number;
}

Downloads the matching superset-<platform>.tar.gz from GitHub Releases and replaces the install root. Only available in built binaries; it errors under bun run dev.

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 ~/.paradev/config.json.

superset organization switch acme
superset org switch org_…

List members in the active organization.

superset organization members list
superset org members list -s satya

List projects on a host. Defaults to this machine; pass --host <id> for another host.

Create a project on a host. Two modes:

• Clone: pass --clone <url> and --parent-dir. The host clones the repo into <parent-dir>/<derived-name>/.
• Import: pass --import <path> to register a repo that already exists on disk.

Either way, the project has no workspaces yet. Create one with superset ws create --project <id> --name local --checkout local --local (the repo's checkout as it is) or --branch <name> (its own worktree).

create always creates a new cloud project, even if your org already has one for the same Git URL. Use projects setup when adopting an existing project on a fresh machine.

superset projects create --name "my-app" --local --clone https://github.com/org/my-app.git --parent-dir ~/code
superset projects create --name "my-app" --local --import ~/code/my-app

Adopt an existing project onto a host without creating a duplicate cloud record. Use it instead of create on a new machine when the repo is already in the org. Find the project ID with projects list (add --host <id> for the host that already has the project). Re-running against a project already set up at the same path is a no-op.

# Pick an ID from `superset projects list`, then clone it onto this machine
superset projects setup 47c31b04-… --local --parent-dir ~/code

# Or register an existing local checkout
superset projects setup 47c31b04-… --local --import ~/code/my-app

List hosts registered to the active organization. A machine registers itself when superset start runs on it, or when you set it up over SSH with hosts add.

superset hosts list

Set up a machine you can SSH into as a host, with nothing typed on it: installs this CLI's version there, signs it in with a new API key sent over ssh stdin, runs it as a user service, and waits for it to come online. Running it again on the same target repairs only what is wrong.

The remote must be macOS or glibc Linux on x64 or arm64 (not Alpine or Windows) and have curl. On Linux it also needs a valid /etc/machine-id, and lingering (loginctl enable-linger) to keep running after you log out. Install and sign in gh there to clone private repos.

superset hosts add me@build-box
superset hosts add build-box --name "Build box" --yes

Undo hosts add: stop the host over SSH and remove its service. If it finds the API key hosts add created, it revokes it and signs the host out; otherwise it leaves the host's sign-in alone. The CLI stays installed, and the host stays listed (offline) until you delete it in Settings → Hosts.

superset hosts remove me@build-box

Set (or clear) the command used to wake a host.

superset hosts set-wake my-sandbox vercel sandbox resume my-box
superset hosts set-wake my-sandbox --clear

Wake a host by running its configured wake command locally, streaming its output.

superset hosts wake my-sandbox

List workspaces. Host workspaces are host-owned; there is no org-wide listing (the desktop app is the cross-host view). projectName falls back to the raw project id when the host does not know the project's name.

Create a workspace on the target host. With --project, specify one of --checkout local, --branch, --pr, or --task (--branch and --pr are mutually exclusive). If you pass --agent, you must also pass --prompt. --command runs a one-off shell command in the workspace directory and is independent of --agent/--prompt. Pass either or both. --model and --effort require --agent; see the agent effort levels below.

--checkout local shares the project's existing files, git index, and checked-out branch. It does not switch branches or run setup. Do not combine it with --branch, --pr, --base-branch, or --skip-branch-prefix. Older hosts reject it without creating a worktree. --local selects this machine and is independent of --checkout local.

Pass --session explicitly to create a session: a project-less workspace backed by a managed folder under ~/.paradev/sessions, initialized as its own git repo. Sessions have no branch semantics, so --branch, --pr, --task, --base-branch, --checkout, --skip-branch-prefix, and --tag are rejected, --name is optional, and the output has no alreadyExists field. Host workspace creation requires either --project <id> or --session; omitting both is an error.

Without --host or --local, the command creates a cloud workspace if your account has cloud workspaces. A cloud workspace takes no project: it starts from an environment, and Paradev creates a new working branch from --base-branch (default: the repository's default branch). --project, --session, --checkout, --branch, --pr, --task, --skip-branch-prefix, and --command are rejected for a cloud workspace. --attachment needs --agent: the files go to the agent through Paradev's storage, up to 200 MB each and 10 at a time. The command returns while the workspace is still provisioning.

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

superset workspaces create \
  --project prj_… \
  --name "review-pr-123" \
  --pr 123 \
  --local

# Project-less session with an agent
superset workspaces create --session --local --agent claude --prompt "…"

# Tags group the workspace into sidebar folders
superset workspaces create --project prj_… --name "perf-spike" --branch perf/spike --local --tag perf

Archive one or more workspaces. Without --host or --local, this targets cloud workspaces if your account has them, else this machine. The old name delete remains an alias.

• Cloud workspace: the sandbox stops within a minute and is deleted after 7 days. A restore within those 7 days keeps its disk; after that, the workspace starts again from a fresh sandbox.
• Worktree workspace on a host: its folder is removed, with any uncommitted changes. Its branch stays, so a restore brings back only committed work. A workspace that shares the project's own checkout keeps that folder.

deleted lists the archived IDs; the field keeps its old name so existing scripts still work. Each ID is reported on its own: unknown IDs land in notFound, errors land in failed with a reason, and the rest of the batch still runs. The command exits non-zero if either list is not empty.

superset workspaces archive ws_a ws_b ws_c

Put a cloud workspace to sleep. Its sandbox stops, every terminal and agent in it ends, and it costs storage only. Files are kept, and opening the workspace wakes it. An agent can run this as its last step, inside its own workspace.

superset workspaces sleep ws_a

Restore an archived cloud workspace. Alias: restore. Within 7 days of archiving it keeps its disk; after that it starts fresh from its environment.

End every terminal and agent on a cloud workspace, so they start again with the current agent sign-ins.

Show a cloud workspace's timeline, oldest first: renames, task links, labels, visibility, sharing, and pull requests. --json keeps every field.

List a cloud workspace's pull requests: those linked to it, and those on its branch. Alias: prs. Outside a cloud workspace and without an id, it lists every cloud workspace's; --archived does too unless an id is given.

Show a cloud workspace's owner, visibility, and who it is shared with.

Share a cloud workspace with members or teams; pass at least one --user or --team. superset workspaces share remove takes the same options and stops sharing. Only the workspace's creator can change who it is shared with.

superset workspaces share add ws_a --user ann@example.com
superset workspaces share remove ws_a --user ann@example.com

Show details for a single workspace on its host. --field is handy in scripts: superset workspaces get --field worktreePath.

superset workspaces get ws_…
superset workspaces get --field branch   # inside a workspace

Update a workspace (default: the cloud if your account has cloud workspaces, else this machine). --tag replaces the whole tag set: tagging is how workspaces group into sidebar folders, so retagging moves the workspace between folders.

On a cloud workspace every field is saved by the API, so it works while the sandbox is asleep. There, --task-id also takes a task slug and adds a link (a cloud workspace can link several tasks), and --clear-task removes them all.

--machine-size is the one field that reaches the sandbox. A running sandbox restarts at the new size: files and uncommitted changes stay, but every terminal and agent on it ends, and agents resume when you open the workspace. A sleeping sandbox starts at the new size the next time it wakes.

superset workspaces update ws_… --name "better-name"
superset workspaces update ws_… --task-id tsk_…
superset workspaces update ws_… --tag perf --tag infra
superset workspaces update ws_… --clear-task
superset workspaces update ws_… --add-label bug --visibility org
superset workspaces update ws_… --machine-size xlarge

Open a workspace in the Paradev desktop app.

url is the superset:// deep link. webUrl is an HTTPS link that opens the same workspace in the desktop app. Use it where only HTTP(S) links are accepted, such as Linear or Slack. workspaces list, get, and create return both fields too. --print prints url; to print the HTTPS link, run superset workspaces get <id> --field webUrl.

superset workspaces open ws_…
superset workspaces open ws_… --print

List the project's git worktrees that have a branch checked out. isMain marks the project's own checkout. workspaceId is the workspace that tracks the worktree, or null when none does yet. Older hosts report only hasWorkspace, so workspaceId is null there even for a tracked worktree.

superset worktrees list --project prj_…

Open one existing worktree as a workspace. The worktree keeps its folder, branch, and files. If a workspace already tracks it, the command returns that workspace with alreadyExists: true and changes nothing, so it is safe to re-run. The project's main checkout is not a worktree; use superset workspaces create --checkout local for it.

To open every untracked worktree, for example after a machine registers as a new host, pass --all (run superset projects setup for the project there first). It returns { opened, alreadyExisted, failed }. If a worktree fails, the others still open, and the command exits non-zero with the same object as its --json output. superset worktrees list shows what --all will open: the rows with isMain: false and hasWorkspace: false.

superset worktrees open --project prj_… --branch fix/login-bug
superset worktrees open --project prj_… --all

List the forwarded ports, with each person's local address and when they forwarded it.

superset ports list

Print where one port is forwarded, one local address per person. Exits non-zero when nobody forwarded it.

superset ports port 5173

List the environments a cloud workspace can start from.

List the repositories the organization's GitHub App can see. These are what --repo accepts.

Create an environment for cloud workspaces to start from.

Rename an environment or change who can use it.

Save a ready cloud workspace as a new environment that new workspaces fork from. Restarts the workspace.

Replace an environment's snapshot with a ready cloud workspace, keeping its name and variables. Restarts the workspace.

Archive an environment. Its snapshot is deleted and no new workspace can start from it.

Set a variable on an environment. secrets list shows the names, never the values, and secrets delete <name> removes one.

Show where the GitHub App is installed and how many repositories it can see.

Install the GitHub App in the browser, then wait until it is installed. Needs the Pro plan and a GitHub account that can install apps on the repositories' owner. integrations github disconnect removes it, and its repositories leave every environment; it asks first, or takes --yes.

Connect your GitHub account in the browser, so your cloud workspaces push and open pull requests as you instead of as the GitHub App. connections github status shows the account, and connections github disconnect removes it.

Sign an agent in for your cloud workspaces. A token or key is read from stdin or a prompt. set codex --kind subscription reads nothing: it starts a ChatGPT device-code sign-in and waits until you approve it in the browser. connections agents list shows which agents are signed in, and connections agents remove <agent> signs one out. For Claude, run claude setup-token and paste the token it prints.

List agents configured on a host. First call on a fresh host seeds the bundled defaults.

superset agents list --local
superset agents list --host host_…

Create an agent session in an existing workspace: starts the named preset (or HostAgentConfig instance) in a fresh terminal session on its host.

superset agents create --workspace ws_… --agent claude --model sonnet --effort high --prompt "Audit the login flow"
superset agents create --workspace ws_… --agent codex --prompt "Review this diff" --attachment ./trace.log
# Restore a killed agent session by the agent's own session id
superset agents create --workspace ws_… --agent claude --resume-session 0b7c…
# Fork a session: a new Claude session with the same conversation
superset agents create --workspace ws_… --agent claude --fork-session 0b7c…
# Hand a terminal's recent output to a different agent
superset agents create --workspace ws_… --agent codex --from-terminal term_…
superset agents create --workspace ws_… --agent codex --from-terminal term_… --context-chars 12000

Pass at most one of --resume-session, --fork-session, and --from-terminal. See Fork and hand off sessions for which agents can fork and what a handoff sends.

Read the agent's saved transcript, beyond the visible screen returned by terminals read. Fails if Paradev cannot read a transcript for that terminal.

superset agents read --local --workspace <workspace-id> --terminal <terminal-id>

Block until an agent reaches a state, instead of polling terminals read. Returns at once if it is already there. Exits 1 on timeout, and at once if the agent exits.

T=$(superset agents create --workspace ws_… --agent claude --prompt "Add a /health route" --json | jq -r .sessionId)
superset agents wait --workspace ws_… --terminal "$T"

{
  terminalId: string;
  state: "starting" | "working" | "blocked" | "idle";
  lastEventType: string | null;
}

Explain why an agent shows its state: its last hook event and when it arrived, how an ended session ended, or that no hook has arrived (an agent Paradev can't see). Useful when agents wait or panes list shows something unexpected.

claude is idle.
Why: its recorded event is Stop, which means its turn ended: it finished, or it was interrupted.
The last hook arrived 1 second ago; the session started 2 seconds ago.

{
  terminalId: string;
  state: "starting" | "working" | "blocked" | "idle" | "exited" | "none";
  because: string;
  details: string[];
  lastEventType: string | null;
  lastEventAt: number | null;
}

Open a fresh PTY in the workspace's worktree, optionally running a command.

superset terminals create --workspace ws_… --command "bun install && bun test"
superset terminals create --workspace ws_…

List the live terminal sessions in a workspace. Presence in the list means the PTY exists, not that an agent inside it is working or idle.

Read a terminal's current screen back as text without mutating the session.

superset terminals read --workspace ws_… --terminal term_… --max-lines 240

Send a follow-up message or key presses to a terminal already running in a workspace, e.g. to give an agent new instructions mid-session, approve a prompt, or interrupt it.

superset terminals send --workspace ws_… --terminal term_… --text "Now add a test" --wait
superset terminals send --workspace ws_… --terminal term_… --keys esc

Block until a terminal's screen matches a pattern, e.g. a dev server's "listening on". matched is the text the pattern matched, which can span lines. Exits 1 on timeout, or at once if the terminal exits first.

superset terminals wait --workspace ws_… --terminal term_… --match "listening on :\d+"

{
  terminalId: string;
  matched: string;
}

Attach this shell to a running terminal. Ctrl+] detaches; the terminal keeps running. Needs an interactive terminal and refuses to run in CI.

superset terminals attach --workspace ws_… --terminal term_…
superset terminals attach --ssh me@build-box --workspace ws_… --terminal term_…

Close (dispose) a terminal running in a workspace. This ends the session.

One read of a host: every workspace, its live terminals, the agent in each with its state, and the pane layout when the desktop app is attached. Use it instead of listing terminals and panes workspace by workspace. An unknown --workspace is an error.

acme-web / health-check  [health-check]  ws_…
  terminal ebed…  "/health route README section"  claude · working
  terminal 63c9…

{
  workspaces: Array<{
    id: string; name: string; project: string | null; branch: string | null;
    terminals: Array<{ id: string; title: string | null; agent: { id: string; state: "starting" | "working" | "blocked" | "idle" } | null }>;
    layout: PaneLayout | null; // as in `panes list`; null without a desktop app
    layoutError: string | null; // set when a desktop app is attached but the layout could not be read
  }>;
}

Tabs and the split tree. row splits are side by side and column splits are stacked, as in CSS flexbox; ratio is the first pane's share. Each terminal pane carries its title and the agent running in it with its state.

row 50/50
  pane-5f00…  terminal  terminal 63c9…  (active)
  pane-03e1…  terminal  "/health route README section"  claude · working  terminal ebed…

{
  activeTabId: string | null;
  tabs: Array<{
    id: string; active: boolean; activePaneId: string | null;
    layout: PaneNode; // { type: "split", direction: "row" | "column", ratio, first, second } | { type: "pane", paneId }
    panes: Array<{
      id: string; kind: string; title: string | null; terminalId: string | null; active: boolean;
      terminalTitle?: string | null;
      agent?: { id: string; state: "starting" | "working" | "blocked" | "idle" } | null;
    }>;
  }>;
}

Open a new tab with a terminal pane, without moving focus.

Split a pane and show a terminal in the new half.

Set a pane's share of the split it sits in. superset panes equalize --workspace <id> [--tab <id>] evens out every split instead.

Move a pane. A tab left empty closes. superset panes swap --workspace <id> --pane A --with B exchanges two panes, and superset panes focus --workspace <id> --pane P focuses one.

Close a pane and end its terminal, as the close button in the app does.

Show a desktop notification. Run from a Paradev terminal, clicking it opens that terminal, so an agent can say "tests pass" and take you straight back. With --host, pass --workspace and --terminal for a click target; without them the click only brings the app forward.

superset notifications show "Tests pass" --body "12 passed" --sound

List the browser panes open in a workspace.

Open a URL in a browser pane and return its paneId. Requires the workspace to be visible in the desktop app (the renderer creates the pane).

superset browser open --workspace ws_… --url http://localhost:3000 --target new-tab

Point an existing pane at a new URL. file://, chrome://, and custom schemes are refused.

Capture a PNG screenshot of the pane's page.

Evaluate JavaScript in the page and return the result for reading or nudging the DOM.

superset browser eval --workspace ws_… --pane pane_… \
  --code "document.querySelector('h1')?.textContent"

Read the pane's captured console output.

Print a raw Chrome DevTools Protocol WebSocket endpoint for the pane, for browser-use / Playwright-class tools (mouse, keyboard, scroll, DOM, network). The URL embeds an auth token; treat it as a secret.

List the Chrome extensions installed in your browser panes. Only extensions installed from the Chrome Web Store appear.

Install a Chrome Web Store extension in your browser panes. The app shows the extension's permission warnings and asks you first; a refusal fails the command, so an agent can't install an extension on its own.

superset browser extensions install <extension-id>

Remove an extension and its data. The app asks you first.

Pin an extension to the browser pane toolbar. superset browser extensions unpin takes the same arguments and unpins it. Neither asks for confirmation.

Without --limit or --cursor, fetches all matching pages and returns a plain array. Either pagination flag selects one batch and returns { items, nextCursor }; nextCursor is null at the end. A cursor without a limit uses 50 rows per batch. Pages are ordered newest-created first. --quiet prints page IDs in either mode. Linked workspaces appear in the WORKSPACE column and in each row's workspaceLinks.

superset pages list --workspace '' --search onboarding --json
superset pages list --workspace '' --limit 20 --json
superset pages list --workspace '' --limit 20 --cursor '<nextCursor>' --json

Publishing the same entry path from the same workspace adds a version to the existing page. Without a workspace, keep the returned ID and pass --page on later publishes to avoid creating another page. Existing visibility is preserved unless explicitly supplied.

Publishing does not open the page in the desktop.

superset pages publish report.html --title "Weekly report" --visibility everyone
superset pages publish report.html --page <page-id> --label "Addressed feedback"

Delete a page and every version. Interactive terminals ask for confirmation unless --yes is passed; non-interactive input does not prompt.

Read what viewers stored with window.superset.storage on a page. Without --key, lists each key with its record count (KEY, RECORDS, UPDATED). With --key, lists each person's value for that key (NAME, VALUE, UPDATED). On a just_me page only the creator can read storage. On an org or everyone page, members of the page's organization can read it, even when the page is public.

superset pages storage weekly-report
superset pages storage weekly-report --key votes --json

List installed plugins, or everything available with --available.

Connects the plugin's account first if it needs one, then writes its skills locally and records the install on your account.

superset plugins install google-calendar

Connect an account to an installed plugin.

Enable an installed plugin.

Disable an installed plugin without dropping it.

Uninstall a plugin and drop its skills.

Reconcile installed plugins with the skill directories agents read and the MCP entries Claude, Codex, and pdev read, adding, refreshing, and reaping both.

add <source> [--name <name>] adds a marketplace from a GitHub repo or local path. list shows the marketplaces on your account. remove <name> removes one.

Scaffold a new plugin and add it to the marketplace.

Validate a plugin or a whole marketplace: manifest, release tag, and whether the built server matches its source.

Cut a version of a plugin: build, record it in the marketplace and the generated bundle, and name the tag to publish it at.

List the tools a connected plugin exposes (PLUGIN, TOOL, DESCRIPTION).

superset mcp tools --plugin slack

Call a tool on a connected plugin and print its result.

superset mcp call-tool search_messages --plugin slack '{"query":"deploy"}'

List the skills installed from plugins on this machine (SKILL, PLUGIN, PATH).

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. Linear issues are archived.

superset tasks delete tsk_a tsk_b

List task statuses in the active organization. Paradev status IDs work with tasks list --status, tasks create --status-id and tasks update --status-id. Linear statuses belong to a team: pass their names or IDs to --status-id on create and update; tasks list --status takes a category (active, started, …) for Linear.

superset tasks statuses list

List automations in the active organization.

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

Create an automation. Pass --rrule for a schedule, or --triggers / --triggers-file for event triggers; one of them is required. Automations are a Pro feature: create, run, and resume need a Pro or Enterprise subscription on the active organization and fail with Automations require the Pro plan. otherwise. Provide --prompt or --prompt-file; if both are present, the inline --prompt value is used. A --project or --workspace must exist on the target host; the CLI verifies this before creating the automation. Omit both for session mode: each run creates a project-less session workspace on the target host.

Every run's created workspace carries the automation's tags, which group it into the matching sidebar folders. By default automations are tagged automation, so their runs collect in an automation folder per project; pass --tag to file runs elsewhere. Tags file the runs; --group files the automation itself in the automations table.

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

List the values an event trigger can filter on (Slack channels, GitHub repositories, Linear teams, ...), with the ids to put in a trigger set. Reports when the provider isn't connected.

superset automations trigger-options --group slack

Update an automation (name, schedule, triggers, agent, host). All flags optional. Omitting a flag preserves the existing value: undefined means "no change", not "clear". Use automations prompt get or automations prompt set to read or replace the prompt body.

Print an automation's prompt body to stdout. The output is the raw prompt with no trailing newline added, so prompt get and prompt set round-trip byte-exactly.

# Read to a file
superset automations prompt get aut_… > prompt.md

# Verify a push landed
superset automations prompt get aut_… | diff - ./prompt.md

Replace an automation's prompt body. The new prompt fully overwrites the old one.

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

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

Archive an automation. It stops firing and leaves automations list; its run history stays.

superset automations archive aut_…

Restore an archived automation. It comes back paused; run automations resume to start it. restore is an alias.

superset automations list --archived
superset automations unarchive aut_…

Permanently delete an archived automation and its run history. This can't be undone. Archive the automation first; an active automation is refused.

superset automations archive aut_…
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_…

List every settable key with its current value, default, and allowed values. isSet: false means the app is using its built-in default.

superset settings list

Print the effective value of one setting (falls back to the app default when unset).

superset settings get terminalFontSize

Set a setting. Booleans accept true/false/on/off/1/0/yes/no; enums and numeric ranges are validated the same way the desktop settings UI validates them.

superset settings set confirmOnQuit false
superset settings set terminalFontSize 16
superset settings set defaultEditor cursor
superset settings set selectedRingtoneId ping

Reset a setting to the app default.

superset settings reset terminalFontSize

List available themes: system (follows OS appearance), the built-ins (dark, light, monokai, catppuccin-latte, solarized-light, vellum), and any custom themes imported through the app.

superset settings theme list

Print the active theme.

superset settings theme get

Export a theme's full JSON definition, the starting point for creating a custom theme: export a built-in, edit the colors, then import it.

superset settings theme export dark --out my-theme.json

Import custom themes, using the same validation and normalization as the desktop's Appearance UI (ids are slugified; missing colors are filled from the built-in base theme; reserved ids like dark are rejected). Re-importing an id replaces that custom theme.

superset settings theme export dark --out my-theme.json
# edit my-theme.json (id, name, ui/terminal/editor colors)
superset settings theme import my-theme.json
superset settings theme set my-theme

Remove a custom theme. If it was the active theme (or a system light/dark mapping), that reference falls back to the default.

superset settings theme remove my-theme

Set the active theme and/or the system light/dark mappings. A running desktop app restyles live; without one the theme applies on next launch. (On app versions without live reload, quit the app first, then set, then relaunch, or the app may overwrite the change.)

superset settings theme set monokai
superset settings theme set system --system-light light --system-dark monokai

Prints the script to stdout unchanged in every output mode: --json, --quiet, and agent environments do not wrap it. The script completes command names at every level (including after an alias, as in superset ws cr<Tab>), each command's flags and their aliases, enum values for flags (--priority=u<Tab>) and arguments, and the global options.

# This shell session
source <(superset completion zsh)
eval "$(superset completion bash)"   # bash 3.2 (macOS's /bin/bash) cannot source a process substitution

# Every session: put the line above in ~/.zshrc or ~/.bashrc, or for zsh
# install the script on fpath so compinit autoloads it
superset completion zsh > ~/.zfunc/_superset   # with fpath=(~/.zfunc $fpath) before compinit

Prints every command, option, and argument as JSON, for tooling that must not parse --help. Commands hidden from this run (internal-only, or unavailable in a cloud workspace) are left out, as they are from --help. Commands and options are sorted and absent fields are omitted, so two versions diff cleanly.

superset schema | jq '.commands[] | select(.path == ["terminals"]) | .commands[].path'

{
  name: "superset";
  version: string;
  globalOptions: SchemaOption[];
  commands: SchemaCommand[];
}

// SchemaCommand
{
  path: string[];            // e.g. ["terminals", "read"]
  description?: string;
  aliases?: string[];
  options: SchemaOption[];
  args: SchemaArg[];
  commands: SchemaCommand[]; // empty for a leaf command
}

// SchemaOption
{
  name: string;              // flag name without the dashes
  aliases: string[];
  type: "string" | "number" | "boolean";
  required: boolean;
  description?: string;
  default?: unknown;
  enum?: string[];
  variadic?: true;
  int?: true;
  min?: number;
  max?: number;
  env?: string;              // environment variable that can supply the value
}

// SchemaArg
{
  name: string;
  required: boolean;
  description?: string;
  enum?: string[];
  variadic?: true;
}

Validates the file before a hand edit or a bad restore surfaces as a confusing auth failure: JSON syntax, the shape of auth, apiKey and organizationId, an expired token, and keys this version does not read. An error exits 1; a warning does not. A missing file is not an error, it only means nobody has logged in yet.

superset config check
superset config check --json

{
  path: string;
  exists: boolean;
  valid: boolean;     // false when any issue is an error
  loggedIn: boolean;  // the file holds a usable credential
  issues: { severity: "error" | "warning"; message: string }[];
}