From 7bc69df5380f2e8176929bd525bafab6fc02c613 Mon Sep 17 00:00:00 2001 From: jonathanpopham Date: Wed, 29 Apr 2026 13:36:29 -0400 Subject: [PATCH 1/2] Add CLI documentation tab MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 /. --- cli/agents.mdx | 85 ++++++++++++ cli/commands.mdx | 292 ++++++++++++++++++++++++++++++++++++++++++ cli/configuration.mdx | 59 +++++++++ cli/file-mode.mdx | 109 ++++++++++++++++ cli/install.mdx | 86 +++++++++++++ cli/overview.mdx | 57 +++++++++ cli/quickstart.mdx | 96 ++++++++++++++ docs.json | 27 ++++ index.mdx | 19 ++- 9 files changed, 820 insertions(+), 10 deletions(-) create mode 100644 cli/agents.mdx create mode 100644 cli/commands.mdx create mode 100644 cli/configuration.mdx create mode 100644 cli/file-mode.mdx create mode 100644 cli/install.mdx create mode 100644 cli/overview.mdx create mode 100644 cli/quickstart.mdx diff --git a/cli/agents.mdx b/cli/agents.mdx new file mode 100644 index 0000000..f508ce5 --- /dev/null +++ b/cli/agents.mdx @@ -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. + + + 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. + diff --git a/cli/commands.mdx b/cli/commands.mdx new file mode 100644 index 0000000..fd19345 --- /dev/null +++ b/cli/commands.mdx @@ -0,0 +1,292 @@ +--- +title: 'Command Reference' +description: 'Every Supermodel CLI command, flag, and alias' +icon: 'terminal' +--- + +Run `supermodel --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. + +```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 # 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 [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 [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. diff --git a/cli/configuration.mdx b/cli/configuration.mdx new file mode 100644 index 0000000..39beda3 --- /dev/null +++ b/cli/configuration.mdx @@ -0,0 +1,59 @@ +--- +title: 'Configuration' +description: 'Config file, environment variables, and CI defaults' +icon: 'gear' +--- + +The CLI reads configuration from `~/.supermodel/config.yaml`. Environment variables override file values, which is especially useful in CI. + +## Config file + +```yaml +# ~/.supermodel/config.yaml +api_key: smsk_live_... # API key (or SUPERMODEL_API_KEY) +api_base: https://api.supermodeltools.com # API base URL (or SUPERMODEL_API_BASE) +output: human # default output format: human | json +files: true # write .graph.* sidecars (or SUPERMODEL_FILES=false) +``` + +## Environment variables + +| Variable | Purpose | +|---|---| +| `SUPERMODEL_API_KEY` | API key. Overrides the config file. | +| `SUPERMODEL_API_BASE` | API base URL. Overrides the config file. | +| `SUPERMODEL_FILES` | Set to `false` to disable `.graph.*` writing globally. | + +## CI / non-interactive use + +For CI, skip `setup` and `login` — set the API key directly: + +```bash +SUPERMODEL_API_KEY=smsk_live_... supermodel analyze --three-file +``` + +Or log in non-interactively with a token: + +```bash +supermodel login --token smsk_live_... +``` + + + Treat `smsk_live_...` keys like passwords. Inject them through your CI's secret store, never commit them. + + +## Cache + +Analysis results are cached locally by content hash. Subsequent commands (`dead-code`, `blast-radius`, `graph`, `find`, `focus`) reuse the cache automatically. Pass `--force` to any analysis command to bypass it. + +Run `supermodel status` to see the cache location. + +## Output formats + +Most analysis commands accept `-o, --output` with at least `human` and `json`. Set `output: json` in the config file to make JSON the default for tools and scripts. + +| Command | Formats | +|---|---| +| `analyze`, `dead-code`, `blast-radius`, `find`, `status` | `human`, `json` | +| `focus` | `markdown`, `json` | +| `graph` | `human`, `json`, `dot` | diff --git a/cli/file-mode.mdx b/cli/file-mode.mdx new file mode 100644 index 0000000..a76a626 --- /dev/null +++ b/cli/file-mode.mdx @@ -0,0 +1,109 @@ +--- +title: 'File Mode' +description: 'Sidecar graph files your agent reads with grep and cat' +icon: 'folder-tree' +--- + +File mode is how Supermodel feeds graph data to AI agents without any agent-specific integration. The CLI writes plain-text sidecars next to every source file, and any agent that can read files can use them. + +## The shard files + +The recommended layout writes three files per source file: + +``` +src/cache.go → src/cache.calls.go # callers and callees with file:line + → src/cache.deps.go # imports and imported-by + → src/cache.impact.go # risk level, domains, blast radius +``` + +This is the **three-file shard format**. It's enabled with `--three-file`: + +```bash +supermodel analyze --three-file +``` + + + Three-file shards are **68% faster** than the legacy single-file `.graph` format because grep matches against function names hit only the `.calls` file, not a combined blob. + + +The legacy format writes one `.graph.` file per source file. It still works — just omit `--three-file`. + +## Watch mode + +Running the bare `supermodel` command enters watch mode: it does a full generate on startup (reusing the cache when possible), then keeps the sidecars fresh as you code. + +```bash +supermodel +``` + +Press `Ctrl+C` to stop. The daemon removes the graph files when it exits cleanly. + +By default the daemon listens on UDP (port `7734`) for change notifications pushed by `supermodel hook`, the Claude Code `PostToolUse` integration. For agents that don't have a hook integration, pass `--fs-watch` to also poll git state (`HEAD`, index mtime, dirty files) every `--poll-interval`. + +| Flag | Default | Description | +|---|---|---| +| `--dir` | `.` | Project directory to watch | +| `--debounce` | `2s` | Debounce before processing changes | +| `--fs-watch` | off | Also poll git state (use when no hook is installed) | +| `--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 | + +## Live updates from Claude Code + +The watch daemon listens on UDP for file-change notifications. Install the `supermodel hook` command as a Claude Code `PostToolUse` hook so every `Write` or `Edit` triggers an incremental update: + +```json +{ + "hooks": { + "PostToolUse": [{ + "matcher": "Write|Edit", + "hooks": [{ "type": "command", "command": "supermodel hook" }] + }] + } +} +``` + +The [setup wizard](/cli/install#first-time-setup) installs this automatically when Claude Code is detected. + +## Teach your agent the files exist + +`supermodel skill` prints a short prompt that explains the shard format. Pipe it into your agent's instructions: + +```bash +supermodel skill >> CLAUDE.md +supermodel skill >> AGENTS.md +supermodel skill >> .cursorrules +``` + +The prompt boils down to: + +``` +This repository has Supermodel graph shard files next to source files. +Files ending in .calls.* contain function call relationships. +Files ending in .deps.* contain dependency relationships. +Files ending in .impact.* contain blast radius data. +Read these files to understand relationships between modules before +making changes. +``` + +## Cleaning up + +To remove every `.graph.*` sidecar from a repo: + +```bash +supermodel clean # remove all +supermodel clean --dry-run # preview what would be removed +``` + + + Add `*.graph.*`, `*.calls.*`, `*.deps.*`, and `*.impact.*` to your `.gitignore` so sidecars stay local. + + +## Disabling file writes + +Set `files: false` in `~/.supermodel/config.yaml`, export `SUPERMODEL_FILES=false`, or pass `--no-shards` to `analyze` to skip writing sidecars entirely. This is useful when you only want JSON output for tools. + +```bash +supermodel analyze --no-shards --output json +``` diff --git a/cli/install.mdx b/cli/install.mdx new file mode 100644 index 0000000..84bcd9a --- /dev/null +++ b/cli/install.mdx @@ -0,0 +1,86 @@ +--- +title: 'Installation' +description: 'Install the Supermodel CLI on macOS, Linux, or Windows' +icon: 'download' +--- + +The CLI is a single Go binary with no runtime dependencies. After install, the `setup` wizard authenticates you and (optionally) installs the Claude Code hook for live updates. + +## macOS (Homebrew) + +```bash +brew install supermodeltools/tap/supermodel +``` + +## Linux & macOS (curl) + +```bash +curl -fsSL https://supermodeltools.com/install.sh | sh +``` + +When attached to a terminal, the install script runs `supermodel setup` automatically on first install. + +## npm + +```bash +npm install -g @supermodeltools/cli +``` + +## From source + +```bash +git clone https://github.com/supermodeltools/cli +cd cli +go build -o supermodel . +``` + +Requires Go 1.22+. + +## First-time setup + +After install, run the interactive wizard. It authenticates your account, picks an output mode, and offers to install the Claude Code hook for live graph updates. + +```bash +supermodel setup +``` + + + In CI or other non-interactive environments, set `SUPERMODEL_API_KEY` instead of running `setup`. See [Configuration](/cli/configuration). + + +## Verify the install + +```bash +supermodel version +supermodel status +``` + +`status` prints your authentication state and cache location. + +## Update + +The CLI can self-update from the latest GitHub release: + +```bash +supermodel update # download and install +supermodel update --check # check without installing +``` + +You can also re-run your original install method — Homebrew and the curl script both detect existing installs and upgrade in place. + +```bash +brew upgrade supermodel +# or +curl -fsSL https://supermodeltools.com/install.sh | sh +``` + +## Uninstall + +```bash +# remove the binary +brew uninstall supermodel # or delete it from your PATH + +# remove credentials and cache +supermodel logout +rm -rf ~/.supermodel +``` diff --git a/cli/overview.mdx b/cli/overview.mdx new file mode 100644 index 0000000..87502a2 --- /dev/null +++ b/cli/overview.mdx @@ -0,0 +1,57 @@ +--- +title: 'Overview' +description: 'The Supermodel CLI gives your AI agent a map of your codebase' +icon: 'terminal' +--- + +The Supermodel CLI maps every file, function, and call relationship in your repo, then writes plain-text `.graph.*` sidecar files next to each source file. Your agent picks them up automatically through its normal file-reading tools — no prompt changes, no extra context windows, no agent-specific integration. + +```bash +curl -fsSL https://supermodeltools.com/install.sh | sh +``` + + + The CLI is the local complement to the [Supermodel API](/index). The CLI calls the same API under the hood, caches results by content hash, and renders them into formats your agent can read. + + +## How it works + + + + Running `supermodel` (the bare command) uploads your repo to the Supermodel API, builds a full call graph, and writes `.graph.*` files next to every source file. It stays running and updates files incrementally as you code. + + + `.graph.*` files are plain text. Any agent that can read files — Claude Code, Cursor, Copilot, Windsurf, Aider — picks them up automatically through `cat` and `grep`. + + + Your agent now has full visibility into your call graph, imports, domains, and blast radius — for every file in the repo, not just the ones open in the editor. + + + +## What you can do with it + + + + Write `.calls`, `.deps`, and `.impact` files next to each source file so any agent can read them. + + + Static analysis surfaces unreachable functions with confidence levels and explanations. + + + See which files and functions a change will impact before you merge it. + + + Expose graph tools to Claude Code or any MCP host via stdio. + + + +## Next steps + + + + Brew, curl, npm, or build from source. + + + Authenticate and generate your first graph in under a minute. + + diff --git a/cli/quickstart.mdx b/cli/quickstart.mdx new file mode 100644 index 0000000..c682222 --- /dev/null +++ b/cli/quickstart.mdx @@ -0,0 +1,96 @@ +--- +title: 'Quickstart' +description: 'Generate graph files and let your agent read them' +icon: 'bolt' +--- + +This guide walks you from a fresh install to your agent reading graph data about every file in your repo. + +## Prerequisites + +1. The CLI [installed](/cli/install). +2. A Supermodel account — sign up at the [Dashboard](https://dashboard.supermodeltools.com/). +3. A local repository to analyze. + +## Step 1: Authenticate + +```bash +supermodel login +``` + +This opens your browser, creates an API key, and saves it to `~/.supermodel/config.yaml`. For CI, pass the key directly: + +```bash +supermodel login --token smsk_live_... +``` + +## Step 2: Generate graph files + +Run a one-shot analysis with the recommended three-file shard format: + +```bash +cd /path/to/your/repo +supermodel analyze --three-file +``` + +This uploads your repo, builds the graph, and writes three sidecar files next to every source file: + +``` +src/cache.go → src/cache.calls.go # who calls what, with file:line + → src/cache.deps.go # imports and imported-by + → src/cache.impact.go # risk level, domains, blast radius +``` + + + The three-file format is **68% faster** in benchmarks than a single combined `.graph` file because grep hits are more targeted. + + +## Step 3: Tell your agent the files exist + +Append the agent awareness prompt to your agent's instructions file: + +```bash +supermodel skill >> CLAUDE.md +# or +supermodel skill >> AGENTS.md +``` + +That's it. The next time your agent edits code in this repo, it will read the relevant `.calls.*`, `.deps.*`, and `.impact.*` files via its normal file-reading tools. + +## Step 4: Keep the graph fresh + +Run the bare command to enter watch/daemon mode. It does a full generate on startup (using the cache when possible), then incrementally re-renders affected files as you code: + +```bash +supermodel +``` + +For Claude Code, install the `PostToolUse` hook so each `Write`/`Edit` triggers an incremental update — the [setup wizard](/cli/install#first-time-setup) does this for you, or add it manually to `.claude/settings.json`: + +```json +{ + "hooks": { + "PostToolUse": [{ + "matcher": "Write|Edit", + "hooks": [{ "type": "command", "command": "supermodel hook" }] + }] + } +} +``` + +## Next steps + + + + Watch daemon, three-file shards, the `skill` prompt, and cleanup. + + + Setup notes for Claude Code, Cursor, Copilot, Windsurf, Aider, and MCP. + + + Every command, flag, and alias. + + + Config file, env vars, and CI-friendly defaults. + + diff --git a/docs.json b/docs.json index 7a35bc9..b545456 100644 --- a/docs.json +++ b/docs.json @@ -42,6 +42,33 @@ } ] }, + { + "tab": "CLI", + "groups": [ + { + "group": "Get started", + "pages": [ + "cli/overview", + "cli/install", + "cli/quickstart" + ] + }, + { + "group": "Guides", + "pages": [ + "cli/file-mode", + "cli/agents", + "cli/configuration" + ] + }, + { + "group": "Reference", + "pages": [ + "cli/commands" + ] + } + ] + }, { "tab": "API Reference", "openapi": "/openapi.yaml" diff --git a/index.mdx b/index.mdx index 46ea2d4..7d842c1 100644 --- a/index.mdx +++ b/index.mdx @@ -11,14 +11,13 @@ Supermodel provides a unified graph representation of your codebase, enabling po **Try the API Playground**: Each endpoint in our API Reference includes an interactive playground. To use it, you'll need an API key from the [Supermodel Dashboard](https://dashboard.supermodeltools.com/). -## API Reference +## Where to start -Explore our data plane endpoints to generate graphs from your code: - - - View the OpenAPI specification and endpoints - + + + View the OpenAPI specification and endpoints. + + + Local CLI that writes graph sidecars next to your source files for any AI agent to read. + + From 756ec059eccf78365aa62d5ff2ec8ed2be77601d Mon Sep 17 00:00:00 2001 From: jonathanpopham Date: Wed, 29 Apr 2026 13:50:08 -0400 Subject: [PATCH 2/2] Rework CLI docs: per-command pages, drop agent/concept fluff MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- cli/agents.mdx | 85 ---------- cli/commands.mdx | 292 ---------------------------------- cli/commands/analyze.mdx | 40 +++++ cli/commands/audit.mdx | 32 ++++ cli/commands/blast-radius.mdx | 45 ++++++ cli/commands/clean.mdx | 27 ++++ cli/commands/compact.mdx | 39 +++++ cli/commands/dead-code.mdx | 39 +++++ cli/commands/docs.mdx | 40 +++++ cli/commands/find.mdx | 36 +++++ cli/commands/focus.mdx | 38 +++++ cli/commands/graph.mdx | 37 +++++ cli/commands/hook.mdx | 36 +++++ cli/commands/login.mdx | 31 ++++ cli/commands/logout.mdx | 18 +++ cli/commands/mcp.mdx | 43 +++++ cli/commands/restore.mdx | 38 +++++ cli/commands/setup.mdx | 18 +++ cli/commands/share.mdx | 26 +++ cli/commands/skill.mdx | 26 +++ cli/commands/status.mdx | 19 +++ cli/commands/update.mdx | 29 ++++ cli/commands/version.mdx | 16 ++ cli/commands/watch.mdx | 44 +++++ cli/configuration.mdx | 59 ------- cli/file-mode.mdx | 109 ------------- cli/install.mdx | 50 +----- cli/overview.mdx | 57 ------- cli/quickstart.mdx | 92 +++-------- docs.json | 34 ++-- index.mdx | 4 +- 31 files changed, 773 insertions(+), 726 deletions(-) delete mode 100644 cli/agents.mdx delete mode 100644 cli/commands.mdx create mode 100644 cli/commands/analyze.mdx create mode 100644 cli/commands/audit.mdx create mode 100644 cli/commands/blast-radius.mdx create mode 100644 cli/commands/clean.mdx create mode 100644 cli/commands/compact.mdx create mode 100644 cli/commands/dead-code.mdx create mode 100644 cli/commands/docs.mdx create mode 100644 cli/commands/find.mdx create mode 100644 cli/commands/focus.mdx create mode 100644 cli/commands/graph.mdx create mode 100644 cli/commands/hook.mdx create mode 100644 cli/commands/login.mdx create mode 100644 cli/commands/logout.mdx create mode 100644 cli/commands/mcp.mdx create mode 100644 cli/commands/restore.mdx create mode 100644 cli/commands/setup.mdx create mode 100644 cli/commands/share.mdx create mode 100644 cli/commands/skill.mdx create mode 100644 cli/commands/status.mdx create mode 100644 cli/commands/update.mdx create mode 100644 cli/commands/version.mdx create mode 100644 cli/commands/watch.mdx delete mode 100644 cli/configuration.mdx delete mode 100644 cli/file-mode.mdx delete mode 100644 cli/overview.mdx diff --git a/cli/agents.mdx b/cli/agents.mdx deleted file mode 100644 index f508ce5..0000000 --- a/cli/agents.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -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. - - - 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. - diff --git a/cli/commands.mdx b/cli/commands.mdx deleted file mode 100644 index fd19345..0000000 --- a/cli/commands.mdx +++ /dev/null @@ -1,292 +0,0 @@ ---- -title: 'Command Reference' -description: 'Every Supermodel CLI command, flag, and alias' -icon: 'terminal' ---- - -Run `supermodel --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. - -```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 # 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 [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 [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. diff --git a/cli/commands/analyze.mdx b/cli/commands/analyze.mdx new file mode 100644 index 0000000..c6cb2d9 --- /dev/null +++ b/cli/commands/analyze.mdx @@ -0,0 +1,40 @@ +--- +title: 'analyze' +description: 'Upload a repository and run the full analysis pipeline' +--- + +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. + +By default, `.graph.*` shard files are written next to each source file. Pass `--no-shards` to skip writing graph files. + +## Synopsis + +```bash +supermodel analyze [path] [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `--three-file` | Generate `.calls`/`.deps`/`.impact` files instead of a single `.graph` | +| `--no-shards` | Skip writing `.graph.*` shard files | +| `--force` | Re-analyze even if a cached result exists | +| `-o, --output` | Output format: `human` \| `json` | +| `-h, --help` | Help for analyze | + +## Examples + +```bash +# Analyze the current directory +supermodel analyze + +# Generate three-file shards (recommended) +supermodel analyze --three-file + +# Re-analyze without using the cache, output JSON +supermodel analyze --force -o json + +# Run analysis without writing sidecar files +supermodel analyze --no-shards +``` diff --git a/cli/commands/audit.mdx b/cli/commands/audit.mdx new file mode 100644 index 0000000..4af816f --- /dev/null +++ b/cli/commands/audit.mdx @@ -0,0 +1,32 @@ +--- +title: 'audit' +description: 'Codebase health report from graph intelligence' +--- + +Analyses the codebase via the Supermodel API and produces a structured Markdown health report covering: + +- Overall status (HEALTHY / DEGRADED / CRITICAL) +- Circular dependency detection +- Domain coupling metrics and high-coupling domains +- High blast-radius files +- Prioritised recommendations + +## Synopsis + +```bash +supermodel audit [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `--dir` | Project directory (default: current working directory) | +| `-h, --help` | Help for audit | + +## Examples + +```bash +supermodel audit +supermodel audit --dir ./path/to/project +``` diff --git a/cli/commands/blast-radius.mdx b/cli/commands/blast-radius.mdx new file mode 100644 index 0000000..a4f129b --- /dev/null +++ b/cli/commands/blast-radius.mdx @@ -0,0 +1,45 @@ +--- +title: 'blast-radius' +description: 'Analyze the impact of changing a file or function' +--- + +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. + +**Aliases:** `br`, `impact` + +## Synopsis + +```bash +supermodel blast-radius [file...] [flags] +``` + +Three usage modes: + +```bash +supermodel blast-radius # analyze a specific file +supermodel blast-radius --diff changes.diff # analyze from a git diff +supermodel blast-radius # global coupling map +``` + +## Flags + +| 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` | +| `-h, --help` | Help for blast-radius | + +## Examples + +```bash +# Impact of changing one file +supermodel blast-radius internal/api/client.go + +# Impact of a pending PR +git diff main...HEAD > /tmp/pr.diff +supermodel blast-radius --diff /tmp/pr.diff + +# Global coupling map (no target) +supermodel blast-radius -o json +``` diff --git a/cli/commands/clean.mdx b/cli/commands/clean.mdx new file mode 100644 index 0000000..1400799 --- /dev/null +++ b/cli/commands/clean.mdx @@ -0,0 +1,27 @@ +--- +title: 'clean' +description: 'Remove all .graph.* files from the repository' +--- + +Removes every `.graph.*` sidecar file from the repository. + +## Synopsis + +```bash +supermodel clean [path] [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `--dry-run` | Show what would be removed without removing | +| `-h, --help` | Help for clean | + +## Examples + +```bash +supermodel clean +supermodel clean --dry-run +supermodel clean ./my-project +``` diff --git a/cli/commands/compact.mdx b/cli/commands/compact.mdx new file mode 100644 index 0000000..1ec0300 --- /dev/null +++ b/cli/commands/compact.mdx @@ -0,0 +1,39 @@ +--- +title: 'compact' +description: 'Reduce token usage of source code while preserving semantics' +--- + +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). + +Supports Go, Python, TypeScript, JavaScript, and Rust. + +For a single file, compacted output is written to stdout. For a directory, files are written to `--output` (default: `./compacted/`). + +**Aliases:** `pack`, `minify` + +## Synopsis + +```bash +supermodel compact [path] [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `-o, --output` | Output directory for directory mode (default `compacted`) | +| `--dry-run` | Print stats without writing files | +| `-h, --help` | Help for compact | + +## Examples + +```bash +# Single file → stdout +supermodel compact internal/api/client.go + +# Whole repo → ./compacted/ +supermodel compact . + +# See savings without writing +supermodel compact --dry-run . +``` diff --git a/cli/commands/dead-code.mdx b/cli/commands/dead-code.mdx new file mode 100644 index 0000000..c0f9dd3 --- /dev/null +++ b/cli/commands/dead-code.mdx @@ -0,0 +1,39 @@ +--- +title: 'dead-code' +description: 'Find unreachable functions using static analysis' +--- + +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. + +**Aliases:** `dc` + +## Synopsis + +```bash +supermodel dead-code [path] [flags] +``` + +## 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` | +| `-h, --help` | Help for dead-code | + +## Examples + +```bash +# High-confidence candidates only +supermodel dead-code --min-confidence high + +# Top 20 results, JSON output +supermodel dead-code --limit 20 -o json + +# Skip vendored and generated code +supermodel dead-code --ignore '**/vendor/**' --ignore '**/*_pb.go' +``` diff --git a/cli/commands/docs.mdx b/cli/commands/docs.mdx new file mode 100644 index 0000000..1a9868e --- /dev/null +++ b/cli/commands/docs.mdx @@ -0,0 +1,40 @@ +--- +title: 'docs' +description: 'Generate static architecture documentation for a repository' +--- + +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. + +The output directory can be served locally or deployed to any static host (GitHub Pages, Vercel, Netlify, Cloudflare Pages). + +## Synopsis + +```bash +supermodel docs [path] [flags] +``` + +## 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 (default `https://example.com`) | +| `--site-name` | Display title for the generated site (default ` Architecture Docs`) | +| `--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 with a custom directory | +| `--force` | Bypass cache and re-upload even if a cached result exists | +| `-h, --help` | Help for docs | + +## Examples + +```bash +supermodel docs + +supermodel docs ./my-project --output ./docs-site + +supermodel docs --repo owner/repo --base-url https://owner.github.io/repo + +supermodel docs --site-name "My App Docs" --output /var/www/html +``` diff --git a/cli/commands/find.mdx b/cli/commands/find.mdx new file mode 100644 index 0000000..fc60482 --- /dev/null +++ b/cli/commands/find.mdx @@ -0,0 +1,36 @@ +--- +title: 'find' +description: 'Find usages and callers of a symbol across the codebase' +--- + +Searches the graph for all nodes matching the given symbol name (substring match, case-insensitive) and prints their call relationships. + +Similar to "Find Usages" in IDEs — without requiring a language server. + +## Synopsis + +```bash +supermodel find [flags] +``` + +## 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` | +| `-h, --help` | Help for find | + +## Examples + +```bash +# Find anything containing this name +supermodel find handleRequest + +# Restrict to classes +supermodel find Client --kind Class + +# JSON output for tool consumption +supermodel find parse -o json +``` diff --git a/cli/commands/focus.mdx b/cli/commands/focus.mdx new file mode 100644 index 0000000..2ad95fe --- /dev/null +++ b/cli/commands/focus.mdx @@ -0,0 +1,38 @@ +--- +title: 'focus' +description: 'Token-efficient graph slice for a single file' +--- + +Extracts the minimal graph context relevant to the given file: direct imports, functions defined, callers, and (optionally) type declarations. + +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. + +**Aliases:** `ctx`, `context` + +## Synopsis + +```bash +supermodel focus [flags] +``` + +## 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`) | +| `-h, --help` | Help for focus | + +## Examples + +```bash +supermodel focus internal/api/client.go + +# Walk imports two hops deep, include types +supermodel focus internal/api/client.go --depth 2 --types + +# JSON for tool consumption +supermodel focus internal/api/client.go -o json +``` diff --git a/cli/commands/graph.mdx b/cli/commands/graph.mdx new file mode 100644 index 0000000..130d799 --- /dev/null +++ b/cli/commands/graph.mdx @@ -0,0 +1,37 @@ +--- +title: 'graph' +description: 'Display the repository graph' +--- + +Fetches or loads the cached graph and renders it in one of three formats: + +- `human` — aligned table of nodes (default) +- `json` — full graph as JSON +- `dot` — Graphviz DOT for use with `dot`/`graphviz` + +## Synopsis + +```bash +supermodel graph [path] [flags] +``` + +## 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`) | +| `-h, --help` | Help for graph | + +## Examples + +```bash +supermodel graph + +# Only files +supermodel graph --label File + +# Render with Graphviz +supermodel graph -o dot | dot -Tsvg > graph.svg +``` diff --git a/cli/commands/hook.mdx b/cli/commands/hook.mdx new file mode 100644 index 0000000..8089afa --- /dev/null +++ b/cli/commands/hook.mdx @@ -0,0 +1,36 @@ +--- +title: 'hook' +description: 'Forward Claude Code file-change events to the watch daemon' +--- + +Reads a Claude Code `PostToolUse` JSON payload from stdin and forwards the file path to the running watch daemon via UDP. Install as a `PostToolUse` hook in `.claude/settings.json`. + +## Synopsis + +```bash +supermodel hook [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `--port` | UDP port of the watch daemon (default `7734`) | +| `-h, --help` | Help for hook | + +## Example + +Add to `.claude/settings.json`: + +```json +{ + "hooks": { + "PostToolUse": [{ + "matcher": "Write|Edit", + "hooks": [{ "type": "command", "command": "supermodel hook" }] + }] + } +} +``` + +The `supermodel setup` wizard installs this automatically when Claude Code is detected. diff --git a/cli/commands/login.mdx b/cli/commands/login.mdx new file mode 100644 index 0000000..4e64914 --- /dev/null +++ b/cli/commands/login.mdx @@ -0,0 +1,31 @@ +--- +title: 'login' +description: 'Authenticate with your Supermodel account' +--- + +Opens your browser to create an API key and automatically saves it to `~/.supermodel/config.yaml`. + +For CI or headless environments, pass the key directly with `--token`. + +## Synopsis + +```bash +supermodel login [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `--token` | API key for non-interactive login (CI) | +| `-h, --help` | Help for login | + +## Examples + +```bash +# Browser-based login +supermodel login + +# Non-interactive (CI) +supermodel login --token smsk_live_... +``` diff --git a/cli/commands/logout.mdx b/cli/commands/logout.mdx new file mode 100644 index 0000000..0ab7eb6 --- /dev/null +++ b/cli/commands/logout.mdx @@ -0,0 +1,18 @@ +--- +title: 'logout' +description: 'Remove stored credentials' +--- + +Removes the API key from `~/.supermodel/config.yaml`. + +## Synopsis + +```bash +supermodel logout [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `-h, --help` | Help for logout | diff --git a/cli/commands/mcp.mdx b/cli/commands/mcp.mdx new file mode 100644 index 0000000..90ce2c3 --- /dev/null +++ b/cli/commands/mcp.mdx @@ -0,0 +1,43 @@ +--- +title: 'mcp' +description: 'Start the Model Context Protocol server' +--- + +Starts a stdio MCP server that exposes Supermodel graph analysis as tools to MCP-compatible hosts. + +## Synopsis + +```bash +supermodel mcp [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `--repo` | Path to the repository root (default `.`) | +| `-h, --help` | Help for mcp | + +## Exposed tools + +| Tool | Description | +|---|---| +| `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 | + +## Example + +Add to `~/.claude/config.json`: + +```json +{ + "mcpServers": { + "supermodel": { + "command": "supermodel", + "args": ["mcp"] + } + } +} +``` diff --git a/cli/commands/restore.mdx b/cli/commands/restore.mdx new file mode 100644 index 0000000..8857945 --- /dev/null +++ b/cli/commands/restore.mdx @@ -0,0 +1,38 @@ +--- +title: 'restore' +description: "Generate a project context summary to restore an agent's understanding" +--- + +Builds a high-level project summary (a "context bomb") and writes it to stdout. Use it after Claude Code compacts its context window to re-establish understanding of your codebase structure, domains, and key files. + +With an API key configured (run `supermodel login`), `restore` calls the Supermodel API for an AI-powered analysis including semantic domains, external dependencies, and critical file ranking. + +Without an API key (or with `--local`), `restore` performs a local scan of the repository file tree and produces a simpler structural summary. + +## Synopsis + +```bash +supermodel restore [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `--dir` | Project directory (default: cwd) | +| `--local` | Use local file scan instead of the Supermodel API | +| `--max-tokens` | Maximum token budget for the output (default `2000`) | +| `-h, --help` | Help for restore | + +## Examples + +```bash +# Pipe into your agent (typical use) +supermodel restore + +# Local-only, no API call +supermodel restore --local + +# Larger budget for big repos +supermodel restore --max-tokens 4000 +``` diff --git a/cli/commands/setup.mdx b/cli/commands/setup.mdx new file mode 100644 index 0000000..00fc493 --- /dev/null +++ b/cli/commands/setup.mdx @@ -0,0 +1,18 @@ +--- +title: 'setup' +description: 'Interactive setup wizard' +--- + +Walks through authentication, repository selection, file mode, and Claude Code hook installation. + +## Synopsis + +```bash +supermodel setup [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `-h, --help` | Help for setup | diff --git a/cli/commands/share.mdx b/cli/commands/share.mdx new file mode 100644 index 0000000..c95a9eb --- /dev/null +++ b/cli/commands/share.mdx @@ -0,0 +1,26 @@ +--- +title: 'share' +description: 'Upload your codebase health report and get a public URL' +--- + +Runs a health audit and uploads the report to supermodeltools.com, returning a short public URL you can share or embed as a README badge. + +## Synopsis + +```bash +supermodel share [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `--dir` | Project directory (default: cwd) | +| `-h, --help` | Help for share | + +## Examples + +```bash +supermodel share +supermodel share --dir ./path/to/project +``` diff --git a/cli/commands/skill.mdx b/cli/commands/skill.mdx new file mode 100644 index 0000000..0706ba6 --- /dev/null +++ b/cli/commands/skill.mdx @@ -0,0 +1,26 @@ +--- +title: 'skill' +description: 'Print agent awareness prompt for graph files' +--- + +Prints a prompt that teaches AI coding agents how to use Supermodel's `.graph.*` sidecar files. Pipe into your agent's instructions file. + +## Synopsis + +```bash +supermodel skill +``` + +## Flags + +| Flag | Description | +|---|---| +| `-h, --help` | Help for skill | + +## Examples + +```bash +supermodel skill >> CLAUDE.md +supermodel skill >> AGENTS.md +supermodel skill >> .cursorrules +``` diff --git a/cli/commands/status.mdx b/cli/commands/status.mdx new file mode 100644 index 0000000..04b7c6f --- /dev/null +++ b/cli/commands/status.mdx @@ -0,0 +1,19 @@ +--- +title: 'status' +description: 'Show authentication and cache status' +--- + +Prints the current authentication state and cache location. + +## Synopsis + +```bash +supermodel status [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `-o, --output` | Output format: `human` \| `json` | +| `-h, --help` | Help for status | diff --git a/cli/commands/update.mdx b/cli/commands/update.mdx new file mode 100644 index 0000000..2b4782f --- /dev/null +++ b/cli/commands/update.mdx @@ -0,0 +1,29 @@ +--- +title: 'update' +description: 'Update supermodel to the latest release' +--- + +Checks for a newer release on GitHub and, if found, downloads and installs it. Independent of authentication — works without an API key. + +## Synopsis + +```bash +supermodel update [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `--check` | Print the latest available version without installing | +| `-h, --help` | Help for update | + +## Examples + +```bash +# Install the latest release +supermodel update + +# Just check +supermodel update --check +``` diff --git a/cli/commands/version.mdx b/cli/commands/version.mdx new file mode 100644 index 0000000..943dff7 --- /dev/null +++ b/cli/commands/version.mdx @@ -0,0 +1,16 @@ +--- +title: 'version' +description: 'Print version information' +--- + +## Synopsis + +```bash +supermodel version [flags] +``` + +## Flags + +| Flag | Description | +|---|---| +| `-h, --help` | Help for version | diff --git a/cli/commands/watch.mdx b/cli/commands/watch.mdx new file mode 100644 index 0000000..022753b --- /dev/null +++ b/cli/commands/watch.mdx @@ -0,0 +1,44 @@ +--- +title: 'supermodel' +description: 'Run the watch daemon (the bare command)' +--- + +Runs a full analysis on startup (using the cached graph if available), then enters daemon mode. Listens for file-change notifications from the `supermodel hook` command and incrementally re-renders affected `.graph.*` sidecar files. Press Ctrl+C to stop and remove graph files. + +## Synopsis + +```bash +supermodel [flags] +``` + +## Description + +The bare `supermodel` command is the watch daemon. It does not take a subcommand — running it with no arguments starts the long-running process. + +By default the daemon listens on UDP (port `7734`) for change notifications pushed by `supermodel hook`. For environments without a hook integration, pass `--fs-watch` to also poll git state (`HEAD`, index mtime, dirty files) every `--poll-interval`. + +## Flags + +| Flag | Default | Description | +|---|---|---| +| `--dir` | `.` | Project directory | +| `--cache-file` | — | Override cache file path | +| `--debounce` | `2s` | Debounce duration before processing changes | +| `--notify-port` | `7734` | UDP port for hook notifications | +| `--fs-watch` | off | Also poll git state (use when no hook is installed) | +| `--poll-interval` | `3s` | Git poll interval (only when `--fs-watch` is set) | +| `-v, --version` | — | Print version and exit | +| `-h, --help` | — | Help for supermodel | + +## Examples + +```bash +# Start the daemon in the current directory +supermodel + +# Watch a specific project, poll git state as a fallback +supermodel --dir ./my-project --fs-watch + +# Use a custom UDP port if 7734 is taken +supermodel --notify-port 9000 +``` diff --git a/cli/configuration.mdx b/cli/configuration.mdx deleted file mode 100644 index 39beda3..0000000 --- a/cli/configuration.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: 'Configuration' -description: 'Config file, environment variables, and CI defaults' -icon: 'gear' ---- - -The CLI reads configuration from `~/.supermodel/config.yaml`. Environment variables override file values, which is especially useful in CI. - -## Config file - -```yaml -# ~/.supermodel/config.yaml -api_key: smsk_live_... # API key (or SUPERMODEL_API_KEY) -api_base: https://api.supermodeltools.com # API base URL (or SUPERMODEL_API_BASE) -output: human # default output format: human | json -files: true # write .graph.* sidecars (or SUPERMODEL_FILES=false) -``` - -## Environment variables - -| Variable | Purpose | -|---|---| -| `SUPERMODEL_API_KEY` | API key. Overrides the config file. | -| `SUPERMODEL_API_BASE` | API base URL. Overrides the config file. | -| `SUPERMODEL_FILES` | Set to `false` to disable `.graph.*` writing globally. | - -## CI / non-interactive use - -For CI, skip `setup` and `login` — set the API key directly: - -```bash -SUPERMODEL_API_KEY=smsk_live_... supermodel analyze --three-file -``` - -Or log in non-interactively with a token: - -```bash -supermodel login --token smsk_live_... -``` - - - Treat `smsk_live_...` keys like passwords. Inject them through your CI's secret store, never commit them. - - -## Cache - -Analysis results are cached locally by content hash. Subsequent commands (`dead-code`, `blast-radius`, `graph`, `find`, `focus`) reuse the cache automatically. Pass `--force` to any analysis command to bypass it. - -Run `supermodel status` to see the cache location. - -## Output formats - -Most analysis commands accept `-o, --output` with at least `human` and `json`. Set `output: json` in the config file to make JSON the default for tools and scripts. - -| Command | Formats | -|---|---| -| `analyze`, `dead-code`, `blast-radius`, `find`, `status` | `human`, `json` | -| `focus` | `markdown`, `json` | -| `graph` | `human`, `json`, `dot` | diff --git a/cli/file-mode.mdx b/cli/file-mode.mdx deleted file mode 100644 index a76a626..0000000 --- a/cli/file-mode.mdx +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: 'File Mode' -description: 'Sidecar graph files your agent reads with grep and cat' -icon: 'folder-tree' ---- - -File mode is how Supermodel feeds graph data to AI agents without any agent-specific integration. The CLI writes plain-text sidecars next to every source file, and any agent that can read files can use them. - -## The shard files - -The recommended layout writes three files per source file: - -``` -src/cache.go → src/cache.calls.go # callers and callees with file:line - → src/cache.deps.go # imports and imported-by - → src/cache.impact.go # risk level, domains, blast radius -``` - -This is the **three-file shard format**. It's enabled with `--three-file`: - -```bash -supermodel analyze --three-file -``` - - - Three-file shards are **68% faster** than the legacy single-file `.graph` format because grep matches against function names hit only the `.calls` file, not a combined blob. - - -The legacy format writes one `.graph.` file per source file. It still works — just omit `--three-file`. - -## Watch mode - -Running the bare `supermodel` command enters watch mode: it does a full generate on startup (reusing the cache when possible), then keeps the sidecars fresh as you code. - -```bash -supermodel -``` - -Press `Ctrl+C` to stop. The daemon removes the graph files when it exits cleanly. - -By default the daemon listens on UDP (port `7734`) for change notifications pushed by `supermodel hook`, the Claude Code `PostToolUse` integration. For agents that don't have a hook integration, pass `--fs-watch` to also poll git state (`HEAD`, index mtime, dirty files) every `--poll-interval`. - -| Flag | Default | Description | -|---|---|---| -| `--dir` | `.` | Project directory to watch | -| `--debounce` | `2s` | Debounce before processing changes | -| `--fs-watch` | off | Also poll git state (use when no hook is installed) | -| `--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 | - -## Live updates from Claude Code - -The watch daemon listens on UDP for file-change notifications. Install the `supermodel hook` command as a Claude Code `PostToolUse` hook so every `Write` or `Edit` triggers an incremental update: - -```json -{ - "hooks": { - "PostToolUse": [{ - "matcher": "Write|Edit", - "hooks": [{ "type": "command", "command": "supermodel hook" }] - }] - } -} -``` - -The [setup wizard](/cli/install#first-time-setup) installs this automatically when Claude Code is detected. - -## Teach your agent the files exist - -`supermodel skill` prints a short prompt that explains the shard format. Pipe it into your agent's instructions: - -```bash -supermodel skill >> CLAUDE.md -supermodel skill >> AGENTS.md -supermodel skill >> .cursorrules -``` - -The prompt boils down to: - -``` -This repository has Supermodel graph shard files next to source files. -Files ending in .calls.* contain function call relationships. -Files ending in .deps.* contain dependency relationships. -Files ending in .impact.* contain blast radius data. -Read these files to understand relationships between modules before -making changes. -``` - -## Cleaning up - -To remove every `.graph.*` sidecar from a repo: - -```bash -supermodel clean # remove all -supermodel clean --dry-run # preview what would be removed -``` - - - Add `*.graph.*`, `*.calls.*`, `*.deps.*`, and `*.impact.*` to your `.gitignore` so sidecars stay local. - - -## Disabling file writes - -Set `files: false` in `~/.supermodel/config.yaml`, export `SUPERMODEL_FILES=false`, or pass `--no-shards` to `analyze` to skip writing sidecars entirely. This is useful when you only want JSON output for tools. - -```bash -supermodel analyze --no-shards --output json -``` diff --git a/cli/install.mdx b/cli/install.mdx index 84bcd9a..a0a516a 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -1,25 +1,23 @@ --- title: 'Installation' -description: 'Install the Supermodel CLI on macOS, Linux, or Windows' +description: 'Install the Supermodel CLI' icon: 'download' --- -The CLI is a single Go binary with no runtime dependencies. After install, the `setup` wizard authenticates you and (optionally) installs the Claude Code hook for live updates. +A single Go binary, no runtime dependencies. -## macOS (Homebrew) +## Homebrew ```bash brew install supermodeltools/tap/supermodel ``` -## Linux & macOS (curl) +## curl ```bash curl -fsSL https://supermodeltools.com/install.sh | sh ``` -When attached to a terminal, the install script runs `supermodel setup` automatically on first install. - ## npm ```bash @@ -34,53 +32,17 @@ cd cli go build -o supermodel . ``` -Requires Go 1.22+. - -## First-time setup - -After install, run the interactive wizard. It authenticates your account, picks an output mode, and offers to install the Claude Code hook for live graph updates. - -```bash -supermodel setup -``` - - - In CI or other non-interactive environments, set `SUPERMODEL_API_KEY` instead of running `setup`. See [Configuration](/cli/configuration). - - -## Verify the install - -```bash -supermodel version -supermodel status -``` - -`status` prints your authentication state and cache location. - ## Update -The CLI can self-update from the latest GitHub release: - ```bash -supermodel update # download and install +supermodel update # install latest release supermodel update --check # check without installing ``` -You can also re-run your original install method — Homebrew and the curl script both detect existing installs and upgrade in place. - -```bash -brew upgrade supermodel -# or -curl -fsSL https://supermodeltools.com/install.sh | sh -``` - ## Uninstall ```bash -# remove the binary -brew uninstall supermodel # or delete it from your PATH - -# remove credentials and cache supermodel logout rm -rf ~/.supermodel +brew uninstall supermodel # or remove the binary from your PATH ``` diff --git a/cli/overview.mdx b/cli/overview.mdx deleted file mode 100644 index 87502a2..0000000 --- a/cli/overview.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: 'Overview' -description: 'The Supermodel CLI gives your AI agent a map of your codebase' -icon: 'terminal' ---- - -The Supermodel CLI maps every file, function, and call relationship in your repo, then writes plain-text `.graph.*` sidecar files next to each source file. Your agent picks them up automatically through its normal file-reading tools — no prompt changes, no extra context windows, no agent-specific integration. - -```bash -curl -fsSL https://supermodeltools.com/install.sh | sh -``` - - - The CLI is the local complement to the [Supermodel API](/index). The CLI calls the same API under the hood, caches results by content hash, and renders them into formats your agent can read. - - -## How it works - - - - Running `supermodel` (the bare command) uploads your repo to the Supermodel API, builds a full call graph, and writes `.graph.*` files next to every source file. It stays running and updates files incrementally as you code. - - - `.graph.*` files are plain text. Any agent that can read files — Claude Code, Cursor, Copilot, Windsurf, Aider — picks them up automatically through `cat` and `grep`. - - - Your agent now has full visibility into your call graph, imports, domains, and blast radius — for every file in the repo, not just the ones open in the editor. - - - -## What you can do with it - - - - Write `.calls`, `.deps`, and `.impact` files next to each source file so any agent can read them. - - - Static analysis surfaces unreachable functions with confidence levels and explanations. - - - See which files and functions a change will impact before you merge it. - - - Expose graph tools to Claude Code or any MCP host via stdio. - - - -## Next steps - - - - Brew, curl, npm, or build from source. - - - Authenticate and generate your first graph in under a minute. - - diff --git a/cli/quickstart.mdx b/cli/quickstart.mdx index c682222..91ffa83 100644 --- a/cli/quickstart.mdx +++ b/cli/quickstart.mdx @@ -1,96 +1,54 @@ --- title: 'Quickstart' -description: 'Generate graph files and let your agent read them' +description: 'Authenticate and run your first analysis' icon: 'bolt' --- -This guide walks you from a fresh install to your agent reading graph data about every file in your repo. - -## Prerequisites - -1. The CLI [installed](/cli/install). -2. A Supermodel account — sign up at the [Dashboard](https://dashboard.supermodeltools.com/). -3. A local repository to analyze. - -## Step 1: Authenticate +## 1. Authenticate ```bash supermodel login ``` -This opens your browser, creates an API key, and saves it to `~/.supermodel/config.yaml`. For CI, pass the key directly: +Opens your browser, creates an API key, and saves it to `~/.supermodel/config.yaml`. For CI, pass the key directly: ```bash supermodel login --token smsk_live_... ``` -## Step 2: Generate graph files - -Run a one-shot analysis with the recommended three-file shard format: +## 2. Analyze a repo ```bash cd /path/to/your/repo -supermodel analyze --three-file +supermodel analyze ``` -This uploads your repo, builds the graph, and writes three sidecar files next to every source file: +Uploads the repo, runs call graph + dependency + domain analysis, caches the result locally by content hash, and writes `.graph.*` sidecar files next to each source file. -``` -src/cache.go → src/cache.calls.go # who calls what, with file:line - → src/cache.deps.go # imports and imported-by - → src/cache.impact.go # risk level, domains, blast radius -``` +## 3. Use the results - - The three-file format is **68% faster** in benchmarks than a single combined `.graph` file because grep hits are more targeted. - +| Goal | Command | +|---|---| +| Find unreachable functions | `supermodel dead-code` | +| See what a change impacts | `supermodel blast-radius path/to/file.go` | +| Codebase health report | `supermodel audit` | +| Find usages of a symbol | `supermodel find handleRequest` | +| Token-efficient context for one file | `supermodel focus path/to/file.go` | +| Print the full graph | `supermodel graph` | -## Step 3: Tell your agent the files exist +Subsequent commands reuse the cached graph automatically. Pass `--force` to any command to bypass the cache. -Append the agent awareness prompt to your agent's instructions file: - -```bash -supermodel skill >> CLAUDE.md -# or -supermodel skill >> AGENTS.md -``` - -That's it. The next time your agent edits code in this repo, it will read the relevant `.calls.*`, `.deps.*`, and `.impact.*` files via its normal file-reading tools. - -## Step 4: Keep the graph fresh - -Run the bare command to enter watch/daemon mode. It does a full generate on startup (using the cache when possible), then incrementally re-renders affected files as you code: - -```bash -supermodel -``` +## 4. Configure (optional) -For Claude Code, install the `PostToolUse` hook so each `Write`/`Edit` triggers an incremental update — the [setup wizard](/cli/install#first-time-setup) does this for you, or add it manually to `.claude/settings.json`: +Settings live at `~/.supermodel/config.yaml`. Environment variables override file values. -```json -{ - "hooks": { - "PostToolUse": [{ - "matcher": "Write|Edit", - "hooks": [{ "type": "command", "command": "supermodel hook" }] - }] - } -} +```yaml +api_key: smsk_live_... # or SUPERMODEL_API_KEY +api_base: https://api.supermodeltools.com # or SUPERMODEL_API_BASE +output: human # human | json +files: true # set false (or SUPERMODEL_FILES=false) to skip writing sidecars ``` -## Next steps +## Next - - - Watch daemon, three-file shards, the `skill` prompt, and cleanup. - - - Setup notes for Claude Code, Cursor, Copilot, Windsurf, Aider, and MCP. - - - Every command, flag, and alias. - - - Config file, env vars, and CI-friendly defaults. - - +See the [command reference](/cli/commands/analyze) for every command, flag, and example. diff --git a/docs.json b/docs.json index b545456..054f38f 100644 --- a/docs.json +++ b/docs.json @@ -48,23 +48,35 @@ { "group": "Get started", "pages": [ - "cli/overview", "cli/install", "cli/quickstart" ] }, { - "group": "Guides", + "group": "Commands", "pages": [ - "cli/file-mode", - "cli/agents", - "cli/configuration" - ] - }, - { - "group": "Reference", - "pages": [ - "cli/commands" + "cli/commands/watch", + "cli/commands/analyze", + "cli/commands/audit", + "cli/commands/blast-radius", + "cli/commands/clean", + "cli/commands/compact", + "cli/commands/dead-code", + "cli/commands/docs", + "cli/commands/find", + "cli/commands/focus", + "cli/commands/graph", + "cli/commands/hook", + "cli/commands/login", + "cli/commands/logout", + "cli/commands/mcp", + "cli/commands/restore", + "cli/commands/setup", + "cli/commands/share", + "cli/commands/skill", + "cli/commands/status", + "cli/commands/update", + "cli/commands/version" ] } ] diff --git a/index.mdx b/index.mdx index 7d842c1..0925a1e 100644 --- a/index.mdx +++ b/index.mdx @@ -17,7 +17,7 @@ Supermodel provides a unified graph representation of your codebase, enabling po View the OpenAPI specification and endpoints. - - Local CLI that writes graph sidecars next to your source files for any AI agent to read. + + Install the Supermodel CLI and start analyzing repositories from your terminal.