Skip to content

Add CLI documentation tab #7

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
jonathanpopham merged 2 commits into from
Apr 29, 2026
Merged

Add CLI documentation tab #7

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7bc69df
Add CLI documentation tab
jonathanpopham Apr 29, 2026
756ec05
Rework CLI docs: per-command pages, drop agent/concept fluff
jonathanpopham Apr 29, 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
85 changes: 85 additions & 0 deletions cli/agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
---
title: 'Connect your agent'
description: 'Setup notes for Claude Code, Cursor, Copilot, Windsurf, Aider, and MCP hosts'
icon: 'robot'
---

`.graph.*` files are plain text read with `cat` and `grep`. Any agent that can read files can use them — the only thing that varies is how each agent picks them up by default.

## At a glance

| Agent | Setup |
|---|---|
| **Claude Code** | Run `supermodel`; install the hook for live updates (the `setup` wizard does this) |
| **Cursor** | Run `supermodel`; sidecars appear in context when you open any source file |
| **GitHub Copilot** | Run `supermodel`; open `.graph.*` files in the editor to include them in context |
| **Windsurf** | Same as Cursor |
| **Aider** | Run `supermodel`, then pass `--read '**/*.graph.*'` to include all graph files |
| **Any other agent** | Run `supermodel` — if it can read files, it can read graph files |

## Claude Code

Claude Code reads sidecar files automatically as it explores your repo. For live updates as you code, install the `PostToolUse` hook so every `Write` or `Edit` triggers an incremental graph update:

```json
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "supermodel hook" }]
}]
}
}
```

The hook command forwards the file path to the running watch daemon over UDP. If no daemon is running, it's a no-op.

## Cursor & Windsurf

Both editors include co-located files in context when you open a source file. After running `supermodel`, the matching `.calls.*`, `.deps.*`, and `.impact.*` sidecars are surfaced automatically.

## GitHub Copilot

Copilot uses files that are open in the editor. Open the relevant `.calls.*` file alongside the source file you're working on to include graph context.

## Aider

Aider's `--read` flag lets you include files as read-only context. Glob the sidecars:

```bash
aider --read '**/*.graph.*'
# or for the three-file format:
aider --read '**/*.calls.*' --read '**/*.deps.*' --read '**/*.impact.*'
```

## MCP server

For agents that speak the [Model Context Protocol](https://modelcontextprotocol.io), the CLI ships a stdio MCP server. It exposes graph analysis as callable tools instead of as files.

Add it to Claude Code (`~/.claude/config.json`):

```json
{
"mcpServers": {
"supermodel": {
"command": "supermodel",
"args": ["mcp"]
}
}
}
```

### Exposed tools

| Tool | What it does |
|---|---|
| `analyze` | Upload repo and run full analysis |
| `dead_code` | Find functions with no callers |
| `blast_radius` | Find files affected by a change |
| `get_graph` | Return a filtered graph slice |

Pass `--repo /path/to/your/repo` to override the working directory.

<Info>
File mode and the MCP server are complementary, not exclusive. File mode covers the passive read path; the MCP server lets agents trigger fresh analysis on demand.
</Info>
292 changes: 292 additions & 0 deletions cli/commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,292 @@
---
title: 'Command Reference'
description: 'Every Supermodel CLI command, flag, and alias'
icon: 'terminal'
---

Run `supermodel <command> --help` for the authoritative help text on any command. This page mirrors that output for browsing.

## Global flags

These flags apply when you run `supermodel` with no subcommand (watch mode):

| Flag | Default | Description |
|---|---|---|
| `--dir` | `.` | Project directory |
| `--debounce` | `2s` | Debounce duration before processing changes |
| `--fs-watch` | off | Also poll git state (fallback for agents without a hook) |
| `--poll-interval` | `3s` | Git poll interval (only when `--fs-watch` is set) |
| `--notify-port` | `7734` | UDP port for hook notifications |
| `--cache-file` | — | Override cache file path |
| `-v, --version` | — | Print version and exit |

---

## File mode

### `analyze`

Upload a repository and run the full analysis pipeline (call graph, dependency, domain). Results are cached locally by content hash; subsequent commands like `dead-code` and `blast-radius` reuse the cache.

```bash
supermodel analyze [path] [flags]
```

| Flag | Description |
|---|---|
| `--three-file` | Generate `.calls`/`.deps`/`.impact` files (recommended) |
| `--no-shards` | Skip writing `.graph.*` shard files |
| `--force` | Re-analyze even if a cached result exists |
| `-o, --output` | Output format: `human` \| `json` |

### `skill`

Print the agent awareness prompt that teaches AI agents how to use `.graph.*` files. Pipe into your agent's instructions:

```bash
supermodel skill >> CLAUDE.md
supermodel skill >> AGENTS.md
supermodel skill >> .cursorrules
```

### `clean`

Remove all `.graph.*` files from the repository.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 29, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Clarify clean scope for three-file shards.

Line 54 says “Remove all .graph.* files,” but the docs now promote .calls.*, .deps.*, and .impact.* as the default shard set. Please explicitly state whether clean removes those too, so users don’t get conflicting expectations.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@cli/commands.mdx` around lines 52 - 55, The docs for the `clean` command
currently say “Remove all `.graph.*` files” which conflicts with the promoted
three-file shard set; update the `clean` command description so it explicitly
lists the full set of shard filenames it removes (e.g., `.graph.*`, `.calls.*`,
`.deps.*`, and `.impact.*`) or state that it removes any shard files matching
the pattern `.{graph,calls,deps,impact}.*`; change the line under the `clean`
heading to unambiguously reflect this behavior so users know exactly which files
`clean` deletes.

```bash
supermodel clean [path] [flags]
```

| Flag | Description |
|---|---|
| `--dry-run` | Show what would be removed without removing |

### `hook`

Forward Claude Code `PostToolUse` events to the watch daemon. Reads a JSON payload from stdin and sends the file path over UDP. Install in `.claude/settings.json` — see [File Mode](/cli/file-mode#live-updates-from-claude-code).

| Flag | Description |
|---|---|
| `--port` | UDP port of the watch daemon (default `7734`) |

---

## On-demand analysis

### `dead-code`

Find unreachable functions using static analysis. Multi-phase pipeline including call graph reachability, entry-point detection, and transitive propagation. Aliases: `dc`.

```bash
supermodel dead-code [path] [flags]
```

| Flag | Description |
|---|---|
| `--min-confidence` | Minimum confidence: `high`, `medium`, or `low` |
| `--limit` | Maximum number of candidates to return |
| `--ignore` | Glob pattern to exclude (repeatable, supports `**`) |
| `--timeout` | Maximum seconds to wait (default `7200`, `0` = no limit) |
| `--force` | Re-analyze even if a cached result exists |
| `-o, --output` | Output format: `human` \| `json` |

### `blast-radius`

Analyze the impact of changing a file or function using call graph and dependency reachability. Aliases: `br`, `impact`.

```bash
supermodel blast-radius <file> # specific file
supermodel blast-radius --diff changes.diff # from a git diff
supermodel blast-radius # global coupling map
```

| Flag | Description |
|---|---|
| `--diff` | Path to a unified diff file (git diff output) |
| `--force` | Re-analyze even if a cached result exists |
| `-o, --output` | Output format: `human` \| `json` |

### `audit`

Codebase health report — overall status, circular dependencies, domain coupling metrics, high blast-radius files, and prioritized recommendations.

```bash
supermodel audit [flags]
```

| Flag | Description |
|---|---|
| `--dir` | Project directory (default: cwd) |

### `find`

Find usages and callers of a symbol across the codebase. Substring match, case-insensitive — like "Find Usages" in an IDE without needing a language server.

```bash
supermodel find <symbol> [flags]
```

| Flag | Description |
|---|---|
| `--kind` | Filter by node label: `Function`, `File`, `Class`, … |
| `--force` | Re-analyze even if cache is fresh |
| `-o, --output` | Output format: `human` \| `json` |

### `focus`

Extract a token-efficient graph slice for a single file: direct imports, defined functions, callers, and (optionally) types. Markdown by default for direct injection into LLM context. Aliases: `ctx`, `context`.

```bash
supermodel focus <file> [flags]
```

| Flag | Description |
|---|---|
| `--depth` | Import traversal depth (default `1`) |
| `--types` | Include type/class declarations |
| `--force` | Re-analyze even if cache is fresh |
| `-o, --output` | Output format: `markdown` \| `json` (default `markdown`) |

### `graph`

Display the cached graph in a human table, JSON, or Graphviz DOT.

```bash
supermodel graph [path] [flags]
```

| Flag | Description |
|---|---|
| `--label` | Filter nodes by label (`File`, `Function`, `Class`, …) |
| `--force` | Re-analyze even if a cached result exists |
| `-o, --output` | Output format: `human` \| `json` \| `dot` (default `human`) |

### `share`

Run a health audit and upload the report to supermodeltools.com, returning a short public URL you can share or embed as a README badge.

```bash
supermodel share [flags]
```

| Flag | Description |
|---|---|
| `--dir` | Project directory (default: cwd) |

---

## Code tools

### `compact`

Reduce token usage by stripping comments, removing blank lines, and shortening local identifiers. Output remains syntactically valid and semantically identical (all tests still pass). Supports Go, Python, TypeScript, JavaScript, and Rust. Aliases: `pack`, `minify`.

```bash
supermodel compact internal/api/client.go # single file → stdout
supermodel compact . # whole repo → ./compacted/
supermodel compact --dry-run . # stats only
```

| Flag | Description |
|---|---|
| `-o, --output` | Output directory for directory mode (default `compacted`) |
| `--dry-run` | Print stats without writing files |

### `docs`

Generate a static HTML site documenting the architecture of a codebase. The site is built by an internal static-site generator from the same graph the API returns, and emits machine-readable artifacts (JSON-LD and `LLMS.txt`) alongside the HTML so AI agents can index it directly. Deploy to any static host (GitHub Pages, Vercel, Netlify, Cloudflare Pages).

```bash
supermodel docs [path] [flags]
```

| Flag | Description |
|---|---|
| `-o, --output` | Output directory (default `./docs-output`) |
| `--repo` | GitHub repo slug `owner/repo` for source links |
| `--base-url` | Canonical base URL where the site will be hosted |
| `--site-name` | Display title for the generated site |
| `--max-entities` | Cap on entity pages (default `12000`, `0` = unlimited) |
| `--max-source-files` | Cap on source files in analysis (default `3000`, `0` = unlimited) |
| `--templates-dir` | Override bundled HTML/CSS/JS templates |
| `--force` | Re-analyze even if a cached result exists |

### `restore`

Build a "context bomb" — a high-level project summary you pipe into your agent after Claude Code compacts its context window. With an API key, calls Supermodel for an AI-powered analysis; otherwise falls back to a local file scan.

```bash
supermodel restore # API analysis (typical)
supermodel restore --local # local file scan, no API call
supermodel restore --max-tokens 4000
```

| Flag | Description |
|---|---|
| `--dir` | Project directory (default: cwd) |
| `--local` | Use local file scan instead of API |
| `--max-tokens` | Token budget for the output (default `2000`) |

---

## Agent integration

### `mcp`

Start a stdio Model Context Protocol server that exposes graph analysis as tools to Claude Code, Hermes, Codex, and any other MCP host. See [Connect your agent → MCP server](/cli/agents#mcp-server) for client setup.

```bash
supermodel mcp [flags]
```

| Flag | Description |
|---|---|
| `--repo` | Path to the repository root (default `.`) |

Exposed tools: `analyze`, `dead_code`, `blast_radius`, `get_graph`.

---

## Auth & config

### `setup`

Interactive setup wizard — authenticates, configures file mode, and offers to install the Claude Code hook.

### `login`

Authenticate with your Supermodel account. Opens your browser and saves the API key.

```bash
supermodel login # interactive
supermodel login --token smsk_live_... # CI / headless
```

### `logout`

Remove stored credentials.

### `status`

Show authentication and cache status.

| Flag | Description |
|---|---|
| `-o, --output` | Output format: `human` \| `json` |

### `update`

Check for and install the latest release. Pulls from GitHub releases. Independent of auth — works without an API key.

```bash
supermodel update # download and install the latest release
supermodel update --check # print the latest available version without installing
```

| Flag | Description |
|---|---|
| `--check` | Check for updates without installing |

### `version`

Print version information.
Loading
Loading