Getting Started

The Paradev CLI (superset) is a single static binary that uses the same backend as the desktop app. Use it to manage workspaces, tasks, automations, and the local host server from a terminal or CI. Scripts and other agents can also dispatch agent tasks with it. paradev is an alias for superset: every install below puts both on PATH.

Install

Desktop app

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

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

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

Standalone install

curl -fsSL https://paradev.com/cli/install.sh | sh

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

Homebrew

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

If you belong to multiple organizations, the CLI asks you to pick one. To skip the prompt:

superset auth login --organization acme

In CI or other non-interactive environments with no browser, use an API key. Store it once with auth login --api-key:

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

Or set SUPERSET_API_KEY 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)

Explore interactively

Bare superset in a terminal opens an interactive command browser. Use the arrow keys to browse commands and flags, and fill in required inputs with guided prompts. A confirmation screen shows the exact command before it runs. superset --help prints the same catalog as static help. Agents and CI always get static help.

Run your first commands

List the projects on this machine. Each one has an id, which later commands take as PROJECT_ID:

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 PROJECT_ID --local --parent-dir ~/code

Then create a workspace against it:

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

Dispatch agent tasks from a script or another agent

One command creates a workspace on its own branch and starts an agent in it with a prompt. Get PROJECT_ID from superset projects list:

superset workspaces create \
  --project PROJECT_ID \
  --name "flaky-tests-2026-10-30" \
  --branch flaky-tests-2026-10-30 \
  --local \
  --agent claude \
  --prompt "Find the flaky test in CI and propose a fix. Do not merge."

Give each task a branch of its own, for example with a date or a task slug. If the branch already has a workspace on the host, the command reuses that workspace (alreadyExists: true in the JSON output) and starts the agent in it, next to any agent already working there.

--local puts the workspace on the machine that runs the command. A CI runner usually exits when the job ends, so from CI target a host that stays on with --host HOST_ID (see Local vs. remote hosts). Projects belong to a host, so use the same --host HOST_ID on every command: get PROJECT_ID from superset projects list --host HOST_ID, and pass --host HOST_ID instead of --local to workspaces create, agents create, and the terminals commands below.

The JSON output has the workspace ID in workspace.id. For each agent, agents[].ok tells you if it started (agents[].error says why not), and agents[].sessionId is its terminal ID. The command can exit 0 when an agent fails to start, so a script should check ok:

superset workspaces create --project PROJECT_ID --name "flaky-tests-2026-10-30" \
  --branch flaky-tests-2026-10-30 --local --agent claude \
  --prompt "Find the flaky test in CI and propose a fix. Do not merge." --json \
  | jq -e '.agents[0].ok'

To start another agent in a workspace that already exists:

superset agents create --workspace WORKSPACE_ID --local --agent codex --prompt "Review the diff and list risks."

Check on the work and read what an agent printed. workspaces list prints each WORKSPACE_ID. terminals list prints only a count in a terminal, so use --json to get each TERMINAL_ID:

superset workspaces list --local
superset terminals list --workspace WORKSPACE_ID --local --json \
  | jq -r '.sessions[].terminalId'
superset terminals read --workspace WORKSPACE_ID --terminal TERMINAL_ID --local

Each dispatched task opens in the desktop and iPhone apps like any other workspace, with its diff ready to review.

Another agent can do the same through the Paradev MCP server. An automation with a webhook trigger starts a run when any service sends a POST to its URL.

Trigger an automation

Run an automation immediately:

superset automations list               # each automation's id is AUTOMATION_ID
superset automations run AUTOMATION_ID
superset automations logs AUTOMATION_ID

Output modes

Commands print a terminal-friendly view by default. Two flags change the output for scripts:

superset tasks list --assignee-me --json | jq '.[].title'
superset workspaces list --quiet | xargs -L1 superset workspaces archive

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 HOST_ID to pick which host handles the request, or --local for this machine. superset hosts list gives each HOST_ID. Local calls go straight to the host server over loopback and work offline. Remote calls route through the cloud API and the relay.

superset hosts list
superset workspaces list --local          # this machine
superset workspaces list --host HOST_ID   # another host

Every host-scoped command targets exactly one host. projects list defaults to this machine. projects create and projects setup require --host or --local. workspaces create, workspaces list, and terminals commands default to the cloud when your account has cloud workspaces, and to this machine when it does not, so pass --local or --host in scripts to get the same host every time. There is no org-wide listing; the desktop app is the cross-host view.

Where state lives

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

SUPERSET_HOME_DIR relocates the whole tree, matching the desktop app.

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