Skip to content

Commit 414f936

Browse files
jonathanpophamjonathanpopham
authored
Add CLI documentation tab (#7)
* Add CLI documentation tab New "CLI" tab covering the Supermodel command-line tool, sourced from the v0.6.0 source tree (cmd/*.go) and authoritative --help output. Pages: cli/overview — what the CLI does, the .graph.* sidecar pattern cli/install — brew, curl, npm, source, setup wizard, self-update cli/quickstart — login → analyze --three-file → skill → watch cli/file-mode — watch daemon, three-file shards, hook, clean cli/agents — Claude Code, Cursor, Copilot, Windsurf, Aider, MCP cli/configuration — config file, env vars, CI defaults cli/commands — full reference for every command, flag, and alias Also surfaces the CLI from the docs landing page (CardGroup with API + CLI) so it's discoverable from /. * Rework CLI docs: per-command pages, drop agent/concept fluff Restructures the CLI tab to match the API reference style — each command gets its own dedicated page. Drops the overview, file-mode, agents, and configuration pages; the CLI is just a CLI, install instructions and a quickstart are enough surrounding context. Navigation: Get started → install, quickstart Commands → one page per subcommand (22 total, including the bare `supermodel` watch daemon) Each command page mirrors the structure used in IDE/terminal docs: synopsis, description, flags table, examples, aliases.
1 parent c5d7d51 commit 414f936

26 files changed

Lines changed: 867 additions & 10 deletions

‎cli/commands/analyze.mdx‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: 'analyze'
3+
description: 'Upload a repository and run the full analysis pipeline'
4+
---
5+
6+
Archives the repository, uploads it to the Supermodel API, and runs call graph generation, dependency analysis, and domain classification. Results are cached locally by content hash. Subsequent commands (`dead-code`, `blast-radius`, `graph`) reuse the cache automatically.
7+
8+
By default, `.graph.*` shard files are written next to each source file. Pass `--no-shards` to skip writing graph files.
9+
10+
## Synopsis
11+
12+
```bash
13+
supermodel analyze [path] [flags]
14+
```
15+
16+
## Flags
17+
18+
| Flag | Description |
19+
|---|---|
20+
| `--three-file` | Generate `.calls`/`.deps`/`.impact` files instead of a single `.graph` |
21+
| `--no-shards` | Skip writing `.graph.*` shard files |
22+
| `--force` | Re-analyze even if a cached result exists |
23+
| `-o, --output` | Output format: `human` \| `json` |
24+
| `-h, --help` | Help for analyze |
25+
26+
## Examples
27+
28+
```bash
29+
# Analyze the current directory
30+
supermodel analyze
31+
32+
# Generate three-file shards (recommended)
33+
supermodel analyze --three-file
34+
35+
# Re-analyze without using the cache, output JSON
36+
supermodel analyze --force -o json
37+
38+
# Run analysis without writing sidecar files
39+
supermodel analyze --no-shards
40+
```

‎cli/commands/audit.mdx‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: 'audit'
3+
description: 'Codebase health report from graph intelligence'
4+
---
5+
6+
Analyses the codebase via the Supermodel API and produces a structured Markdown health report covering:
7+
8+
- Overall status (HEALTHY / DEGRADED / CRITICAL)
9+
- Circular dependency detection
10+
- Domain coupling metrics and high-coupling domains
11+
- High blast-radius files
12+
- Prioritised recommendations
13+
14+
## Synopsis
15+
16+
```bash
17+
supermodel audit [flags]
18+
```
19+
20+
## Flags
21+
22+
| Flag | Description |
23+
|---|---|
24+
| `--dir` | Project directory (default: current working directory) |
25+
| `-h, --help` | Help for audit |
26+
27+
## Examples
28+
29+
```bash
30+
supermodel audit
31+
supermodel audit --dir ./path/to/project
32+
```

‎cli/commands/blast-radius.mdx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: 'blast-radius'
3+
description: 'Analyze the impact of changing a file or function'
4+
---
5+
6+
Uploads the repository to the Supermodel API and runs impact analysis using call graph and dependency graph reachability. Results include risk scoring, affected files and functions, and entry points that would be impacted by changes to the target.
7+
8+
**Aliases:** `br`, `impact`
9+
10+
## Synopsis
11+
12+
```bash
13+
supermodel blast-radius [file...] [flags]
14+
```
15+
16+
Three usage modes:
17+
18+
```bash
19+
supermodel blast-radius <file> # analyze a specific file
20+
supermodel blast-radius --diff changes.diff # analyze from a git diff
21+
supermodel blast-radius # global coupling map
22+
```
23+
24+
## Flags
25+
26+
| Flag | Description |
27+
|---|---|
28+
| `--diff` | Path to a unified diff file (git diff output) |
29+
| `--force` | Re-analyze even if a cached result exists |
30+
| `-o, --output` | Output format: `human` \| `json` |
31+
| `-h, --help` | Help for blast-radius |
32+
33+
## Examples
34+
35+
```bash
36+
# Impact of changing one file
37+
supermodel blast-radius internal/api/client.go
38+
39+
# Impact of a pending PR
40+
git diff main...HEAD > /tmp/pr.diff
41+
supermodel blast-radius --diff /tmp/pr.diff
42+
43+
# Global coupling map (no target)
44+
supermodel blast-radius -o json
45+
```

‎cli/commands/clean.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: 'clean'
3+
description: 'Remove all .graph.* files from the repository'
4+
---
5+
6+
Removes every `.graph.*` sidecar file from the repository.
7+
8+
## Synopsis
9+
10+
```bash
11+
supermodel clean [path] [flags]
12+
```
13+
14+
## Flags
15+
16+
| Flag | Description |
17+
|---|---|
18+
| `--dry-run` | Show what would be removed without removing |
19+
| `-h, --help` | Help for clean |
20+
21+
## Examples
22+
23+
```bash
24+
supermodel clean
25+
supermodel clean --dry-run
26+
supermodel clean ./my-project
27+
```

‎cli/commands/compact.mdx‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: 'compact'
3+
description: 'Reduce token usage of source code while preserving semantics'
4+
---
5+
6+
Strips comments, removes blank lines, and shortens local identifiers to produce token-efficient source code that remains syntactically valid and semantically identical (all tests still pass).
7+
8+
Supports Go, Python, TypeScript, JavaScript, and Rust.
9+
10+
For a single file, compacted output is written to stdout. For a directory, files are written to `--output` (default: `./compacted/`).
11+
12+
**Aliases:** `pack`, `minify`
13+
14+
## Synopsis
15+
16+
```bash
17+
supermodel compact [path] [flags]
18+
```
19+
20+
## Flags
21+
22+
| Flag | Description |
23+
|---|---|
24+
| `-o, --output` | Output directory for directory mode (default `compacted`) |
25+
| `--dry-run` | Print stats without writing files |
26+
| `-h, --help` | Help for compact |
27+
28+
## Examples
29+
30+
```bash
31+
# Single file → stdout
32+
supermodel compact internal/api/client.go
33+
34+
# Whole repo → ./compacted/
35+
supermodel compact .
36+
37+
# See savings without writing
38+
supermodel compact --dry-run .
39+
```

‎cli/commands/dead-code.mdx‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: 'dead-code'
3+
description: 'Find unreachable functions using static analysis'
4+
---
5+
6+
Uploads the repository to the Supermodel API and runs multi-phase dead code analysis including call graph reachability, entry point detection, and transitive propagation. Results include confidence levels (high/medium/low), line numbers, and explanations for why each function was flagged.
7+
8+
**Aliases:** `dc`
9+
10+
## Synopsis
11+
12+
```bash
13+
supermodel dead-code [path] [flags]
14+
```
15+
16+
## Flags
17+
18+
| Flag | Description |
19+
|---|---|
20+
| `--min-confidence` | Minimum confidence: `high`, `medium`, or `low` |
21+
| `--limit` | Maximum number of candidates to return |
22+
| `--ignore` | Glob pattern to exclude (repeatable, supports `**`) |
23+
| `--timeout` | Maximum seconds to wait (default `7200`, `0` = no limit) |
24+
| `--force` | Re-analyze even if a cached result exists |
25+
| `-o, --output` | Output format: `human` \| `json` |
26+
| `-h, --help` | Help for dead-code |
27+
28+
## Examples
29+
30+
```bash
31+
# High-confidence candidates only
32+
supermodel dead-code --min-confidence high
33+
34+
# Top 20 results, JSON output
35+
supermodel dead-code --limit 20 -o json
36+
37+
# Skip vendored and generated code
38+
supermodel dead-code --ignore '**/vendor/**' --ignore '**/*_pb.go'
39+
```

‎cli/commands/docs.mdx‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: 'docs'
3+
description: 'Generate static architecture documentation for a repository'
4+
---
5+
6+
Generates a static HTML site documenting the architecture of a codebase. The command uploads the repository to the Supermodel API, converts the returned code graph to markdown, and builds a browsable static site with search, dependency graphs, taxonomy navigation, and SEO metadata. The site also emits machine-readable artifacts (JSON-LD and `LLMS.txt`) alongside the HTML.
7+
8+
The output directory can be served locally or deployed to any static host (GitHub Pages, Vercel, Netlify, Cloudflare Pages).
9+
10+
## Synopsis
11+
12+
```bash
13+
supermodel docs [path] [flags]
14+
```
15+
16+
## Flags
17+
18+
| Flag | Description |
19+
|---|---|
20+
| `-o, --output` | Output directory (default `./docs-output`) |
21+
| `--repo` | GitHub repo slug `owner/repo` for source links |
22+
| `--base-url` | Canonical base URL where the site will be hosted (default `https://example.com`) |
23+
| `--site-name` | Display title for the generated site (default `<repo> Architecture Docs`) |
24+
| `--max-entities` | Cap on entity pages (default `12000`, `0` = unlimited) |
25+
| `--max-source-files` | Cap on source files in analysis (default `3000`, `0` = unlimited) |
26+
| `--templates-dir` | Override bundled HTML/CSS/JS templates with a custom directory |
27+
| `--force` | Bypass cache and re-upload even if a cached result exists |
28+
| `-h, --help` | Help for docs |
29+
30+
## Examples
31+
32+
```bash
33+
supermodel docs
34+
35+
supermodel docs ./my-project --output ./docs-site
36+
37+
supermodel docs --repo owner/repo --base-url https://owner.github.io/repo
38+
39+
supermodel docs --site-name "My App Docs" --output /var/www/html
40+
```

‎cli/commands/find.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: 'find'
3+
description: 'Find usages and callers of a symbol across the codebase'
4+
---
5+
6+
Searches the graph for all nodes matching the given symbol name (substring match, case-insensitive) and prints their call relationships.
7+
8+
Similar to "Find Usages" in IDEs — without requiring a language server.
9+
10+
## Synopsis
11+
12+
```bash
13+
supermodel find <symbol> [flags]
14+
```
15+
16+
## Flags
17+
18+
| Flag | Description |
19+
|---|---|
20+
| `--kind` | Filter by node label: `Function`, `File`, `Class`, … |
21+
| `--force` | Re-analyze even if cache is fresh |
22+
| `-o, --output` | Output format: `human` \| `json` |
23+
| `-h, --help` | Help for find |
24+
25+
## Examples
26+
27+
```bash
28+
# Find anything containing this name
29+
supermodel find handleRequest
30+
31+
# Restrict to classes
32+
supermodel find Client --kind Class
33+
34+
# JSON output for tool consumption
35+
supermodel find parse -o json
36+
```

‎cli/commands/focus.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: 'focus'
3+
description: 'Token-efficient graph slice for a single file'
4+
---
5+
6+
Extracts the minimal graph context relevant to the given file: direct imports, functions defined, callers, and (optionally) type declarations.
7+
8+
Output is structured markdown for direct injection into LLM context windows, keeping token usage minimal while preserving semantic relevance. Use `--output json` for structured consumption by tools.
9+
10+
**Aliases:** `ctx`, `context`
11+
12+
## Synopsis
13+
14+
```bash
15+
supermodel focus <file> [flags]
16+
```
17+
18+
## Flags
19+
20+
| Flag | Description |
21+
|---|---|
22+
| `--depth` | Import traversal depth (default `1`) |
23+
| `--types` | Include type/class declarations |
24+
| `--force` | Re-analyze even if cache is fresh |
25+
| `-o, --output` | Output format: `markdown` \| `json` (default `markdown`) |
26+
| `-h, --help` | Help for focus |
27+
28+
## Examples
29+
30+
```bash
31+
supermodel focus internal/api/client.go
32+
33+
# Walk imports two hops deep, include types
34+
supermodel focus internal/api/client.go --depth 2 --types
35+
36+
# JSON for tool consumption
37+
supermodel focus internal/api/client.go -o json
38+
```

‎cli/commands/graph.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: 'graph'
3+
description: 'Display the repository graph'
4+
---
5+
6+
Fetches or loads the cached graph and renders it in one of three formats:
7+
8+
- `human` — aligned table of nodes (default)
9+
- `json` — full graph as JSON
10+
- `dot` — Graphviz DOT for use with `dot`/`graphviz`
11+
12+
## Synopsis
13+
14+
```bash
15+
supermodel graph [path] [flags]
16+
```
17+
18+
## Flags
19+
20+
| Flag | Description |
21+
|---|---|
22+
| `--label` | Filter nodes by label (`File`, `Function`, `Class`, …) |
23+
| `--force` | Re-analyze even if a cached result exists |
24+
| `-o, --output` | Output format: `human` \| `json` \| `dot` (default `human`) |
25+
| `-h, --help` | Help for graph |
26+
27+
## Examples
28+
29+
```bash
30+
supermodel graph
31+
32+
# Only files
33+
supermodel graph --label File
34+
35+
# Render with Graphviz
36+
supermodel graph -o dot | dot -Tsvg > graph.svg
37+
```

0 commit comments

Comments
 (0)