Skip to content

docs: reorg sidebar, merge install+overview, add CLI section, rewrite MCP for v2 #3926

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
saddlepaddle merged 2 commits into from
May 1, 2026
Merged

docs: reorg sidebar, merge install+overview, add CLI section, rewrite MCP for v2 #3926

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cb68a2f
docs: reorg sidebar, merge installation+overview, add CLI section, re…
saddlepaddle Apr 30, 2026
30c6ffa
docs: address PR review — Amp tab last, paraphrase host server error …
saddlepaddle Apr 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 50 additions & 16 deletions apps/docs/content/docs/cli/cli-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@ title: CLI Reference
description: Complete reference for Superset command-line interface, including commands and flags.
---

<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>

## Synopsis

```text
Expand Down Expand Up @@ -139,7 +143,7 @@ Auth: Session (expires in 32 min)

### start

Start the local host service — the daemon the CLI and desktop app both
Start the local host server — the daemon the CLI and desktop app both
talk to when targeting this machine.

<Command
Expand All @@ -150,7 +154,7 @@ talk to when targeting this machine.
]}
>
If a manifest exists and the PID is alive, returns the existing
instance's details. Otherwise spawns the host service binary, polls
instance's details. 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.

Expand All @@ -159,7 +163,7 @@ superset start --daemon
```

<CommandReturns>
The running host service.
The running host server.

<JsonOutput>
```ts
Expand All @@ -175,7 +179,7 @@ The running host service.

### stop

Stop the local host service.
Stop the local host server.

<Command name="superset stop">
Sends SIGTERM, waits up to 10 seconds, sends SIGKILL if still alive. The
Expand All @@ -186,7 +190,7 @@ superset stop
```

<CommandReturns>
The stopped host service, if one was running.
The stopped host server, if one was running.

<JsonOutput>
```ts
Expand All @@ -202,7 +206,7 @@ The stopped host service, if one was running.

### status

Inspect the local host service.
Inspect the local host server.

<Command name="superset status">
`healthy` reflects a live `health.check` request (2-second timeout).
Expand All @@ -212,7 +216,7 @@ superset status
```

<CommandReturns>
The host service state. Three shapes depending on what's running.
The host server state. Three shapes depending on what's running.

<JsonOutput>
```ts
Expand Down Expand Up @@ -244,7 +248,7 @@ The host service state. Three shapes depending on what's running.

### update

Update the Superset CLI and host service binary.
Update the Superset CLI and host server binary.

<Command
name="superset update"
Expand Down Expand Up @@ -335,8 +339,9 @@ superset org switch org_…

### projects

Projects are checked-out repos that live on a specific host. v1 ships
read-only; create projects from the desktop app.
Projects are checked-out repos that live on a specific host. The host
clones (or registers) the repo, creates the cloud record, and makes it
available to every machine in the organization.

<Command
name="superset projects list"
Expand All @@ -355,12 +360,42 @@ read-only; create projects from the desktop app.
List projects on the target host.
</Command>

<Command
name="superset projects create"
options={[
{ flag: "--name <name>", required: true, description: "Display name for the project." },
{ flag: "--url <url>", description: "Clone from a Git URL. Mutually exclusive with `--path`." },
{ flag: "--parent-dir <path>", description: "Where to clone into. Required with `--url`." },
{ flag: "--path <path>", description: "Import an existing local repo. Mutually exclusive with `--url`." },
{ flag: "--host <id>", description: "Target host. Defaults to the local machine." },
]}
output={`{
projectId: string;
repoPath: string;
mainWorkspaceId: string | null;
}`}
>
Register a project on a host. Two modes:

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

Either way, the cloud project row is created and the host's main workspace
is ensured.

```bash
superset projects create --name "my-app" --url https://github.com/org/my-app.git --parent-dir ~/code
superset projects create --name "my-app" --path ~/code/my-app
```
</Command>
Comment on lines +363 to +391
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add an explicit availability caveat for projects create.

This section reads as fully GA, but the PR notes wrapper shipping is still pending. Without a note, users can hit command/tooling mismatch immediately.

Proposed doc tweak 
 <Command
 	name="superset projects create"
@@
 >
+<Callout type="warn">
+`superset projects create` may not be available in older CLI builds yet.
+If you don't see this command, upgrade to the latest CLI release.
+</Callout>
+
 Register a project on a host. Two modes:
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<Command
name="superset projects create"
options={[
{ flag: "--name <name>", required: true, description: "Display name for the project." },
{ flag: "--url <url>", description: "Clone from a Git URL. Mutually exclusive with `--path`." },
{ flag: "--parent-dir <path>", description: "Where to clone into. Required with `--url`." },
{ flag: "--path <path>", description: "Import an existing local repo. Mutually exclusive with `--url`." },
{ flag: "--host <id>", description: "Target host. Defaults to the local machine." },
]}
output={`{
projectId: string;
repoPath: string;
mainWorkspaceId: string | null;
}`}
>
Register a project on a host. Two modes:
- **Clone** — pass `--url` and `--parent-dir`. The host clones the repo
into `<parent-dir>/<derived-name>/`.
- **Import** — pass `--path` to register a repo that already exists on disk.
Either way, the cloud project row is created and the host's main workspace
is ensured.
```bash
superset projects create --name "my-app" --url https://github.com/org/my-app.git --parent-dir ~/code
superset projects create --name "my-app" --path ~/code/my-app
```
</Command>
<Command
name="superset projects create"
options={[
{ flag: "--name <name>", required: true, description: "Display name for the project." },
{ flag: "--url <url>", description: "Clone from a Git URL. Mutually exclusive with `--path`." },
{ flag: "--parent-dir <path>", description: "Where to clone into. Required with `--url`." },
{ flag: "--path <path>", description: "Import an existing local repo. Mutually exclusive with `--url`." },
{ flag: "--host <id>", description: "Target host. Defaults to the local machine." },
]}
output={`{
projectId: string;
repoPath: string;
mainWorkspaceId: string | null;
}`}
>
<Callout type="warn">
`superset projects create` may not be available in older CLI builds yet.
If you don't see this command, upgrade to the latest CLI release.
</Callout>
Register a project on a host. Two modes:
- **Clone** — pass `--url` and `--parent-dir`. The host clones the repo
into `<parent-dir>/<derived-name>/`.
- **Import** — pass `--path` to register a repo that already exists on disk.
Either way, the cloud project row is created and the host's main workspace
is ensured.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@apps/docs/content/docs/cli/cli-reference.mdx` around lines 363 - 391, Add an
explicit availability caveat under the Command block for name="superset projects
create" stating that the CLI wrapper or hosting integration is not yet generally
available (GA) and that the command may not be available or may require a
specific wrapper version; update the prose immediately after the description
(near the "Register a project on a host." paragraph) to include a short note
about the pending wrapper shipping and any workaround (e.g., use local host only
or specific version) so readers are aware of possible command/tooling
mismatches.


---

### hosts

Discover hosts registered to the active organization. To control the
host service running on this machine, use [`start`](#start),
host server running on this machine, use [`start`](#start),
[`stop`](#stop), and [`status`](#status).

<Command
Expand Down Expand Up @@ -389,13 +424,12 @@ superset hosts list
Workspaces are branch-scoped working copies on a host.

**Routing:** when `--host` resolves to the local machine, the CLI calls
the host service directly over loopback HTTP — no cloud roundtrip, works
the host server directly over loopback HTTP — no cloud roundtrip, works
offline. Otherwise it routes through the cloud API and the relay.

If the resolved host is the local machine but the host service isn't
responding, the CLI errors with
`Host service for this machine isn't running. Run: superset start.`
rather than silently falling through to the cloud.
If the resolved host is the local machine but the host server isn't
responding, the CLI errors out and points you at `superset start` rather
than silently falling through to the cloud.

<Command
name="superset workspaces list"
Expand Down
3 changes: 2 additions & 1 deletion apps/docs/content/docs/cli/env-vars.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,5 @@ CI environment to apply them across every session.
| Variable | Description |
| --- | --- |
| `SUPERSET_API_KEY` | API key (`sk_live_…` / `sk_test_…`) used in place of stored OAuth login. Equivalent to `--api-key`. |
| `SUPERSET_HOME_DIR` | Directory the CLI uses for `config.json` and the host service tree. Default: `~/.superset`. Shared with the desktop app. |
| `SUPERSET_HOME_DIR` | Directory the CLI uses for `config.json` and the host server tree. Default: `~/.superset`. Shared with the desktop app. |
| `GH_TOKEN` / `GITHUB_TOKEN` | Read by the `gh` CLI the host server shells out to for PR checkout and metadata. Set this for sandboxes or CI instead of running `gh auth login` interactively. |
61 changes: 17 additions & 44 deletions apps/docs/content/docs/cli/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,38 +3,28 @@ title: Getting Started
description: Install the Superset CLI, sign in, and run your first commands.
---

<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 service from your terminal or from CI.
and the local host server from your terminal or from CI.

## Install

### macOS (Apple Silicon)

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

The script downloads the latest `superset-darwin-arm64` binary and installs
it at `/usr/local/bin/superset`.
The script auto-detects your platform (macOS Apple Silicon or Linux x86_64) and installs the binary at `/usr/local/bin/superset`.

### Linux (x86_64)
### Homebrew

```bash
curl -fsSL https://app.superset.sh/install.sh | sh
brew install superset-sh/tap/superset
```

### From source

```bash
git clone https://github.com/superset-sh/superset.git
cd superset
bun install
bun --filter @superset/cli build
```

The built binary lands at `packages/cli/dist/superset`.

## Sign in

```bash
Expand All @@ -45,21 +35,22 @@ The CLI starts a loopback callback server on `127.0.0.1:51789` (or `51790`
if busy), opens your browser to the consent page, and stores a session
token at `~/.superset/config.json`.

If you belong to multiple organizations and stdout is a TTY, you'll be
prompted to pick one. In CI or any non-TTY environment, pass it explicitly:
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
```

To use an API key instead of OAuth (recommended for CI):
For CI or other non-interactive environments — where there's no browser to
complete the OAuth flow — use an API key instead:

```bash
export SUPERSET_API_KEY=sk_live_…
superset auth whoami
```

API keys are issued from the **Settings → API Keys** page in the web app.
API keys are issued from the **Settings → API Keys** page in the desktop app.

## Verify your session

Expand All @@ -73,24 +64,6 @@ Organization: Acme
Auth: Session (expires in 32 min)
```

## Start the local host service

The host service is the daemon that the CLI and desktop app both talk to
when targeting the local machine. It manages workspaces, ports, and agent
runs. The desktop app starts it automatically; from the CLI:

```bash
superset start --daemon
```

```bash
superset status
```

Stop it again with `superset stop`. State is shared with the desktop
app under `~/.superset/host/<organizationId>/`, so a host service started
by either client is visible to both.

## Run your first commands

List workspaces on the local machine:
Expand Down Expand Up @@ -140,8 +113,8 @@ output unless you pass `--quiet`.
## Local vs. remote hosts

`workspaces`, `projects`, and `automations create/update` accept a
`--host <id>` flag to pick which host services the request. When omitted,
the CLI targets the local machine, talks directly to the host service over
`--host <id>` flag to pick which host handles the request. When omitted,
the CLI targets the local machine, talks directly to the host server over
loopback, and works offline.

To target a different host:
Expand All @@ -158,8 +131,8 @@ identical.

```text
~/.superset/config.json # auth, active organization
~/.superset/host/<organizationId>/manifest.json # host service endpoint + token
~/.superset/host/<organizationId>/host.db # local host service DB
~/.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.
Expand Down
Loading
Loading