Every expandai command, argument, flag, and default. Fetch a page, highlight it, read its Appendix, sign in, set up a coding agent, and clean up.
expandai is the Expand command line. You give it a URL and get Markdown text back on stdout, or a JSON object with --format json. The same binary signs you in, runs the local MCP server, and installs the Expand Skill and hooks into coding agents.
npm install -g expandai
Every command also runs without a global install, through npx -y expandai <command>.
Fetch a page and print Markdown text. --format json prints a JSON object.
expandai fetch <url> --highlights <query>
Fetch a page and print Fetch Highlights for the query.
expandai snapshots get <snapshotId>
Read the public Snapshot catalog.
Note
Batched Fetch has no CLI command. Start and poll a run through the TypeScript SDK or the API. See Batched Fetch.
Fetch
expandai fetch <url>
Fetch a page and print it.
expandai fetch https://www.figma.com/pricing/
Argument
Definition
url
The page to fetch. http or https only. Input without a scheme gets https:// added. The hostname needs a dot, or is localhost.
Option
Definition
Default
--format
text prints Markdown text. json prints a JSON object.
text
--highlights
A query. Prints Fetch Highlights for it instead of the page.
None
Note
The CLI has no --include flag, so the include options stay at their defaults. To choose layers, use the TypeScript SDK or the API.
Without --highlights, --format text is Markdown Mode: the CLI calls POST /v1/fetch and prints the Markdown text, frontmatter first. --format json is JSON Mode: the CLI calls POST /v1/fetch/json and prints the JSON object, with the Main Markdown in markdown, the State JSON in json, and the Snapshot in meta.
When the Fetch returns no Markdown, the command fails with No markdown content was returned. When the origin never answered, --format text fails with the reason, and --format json prints the origin error object instead of content. See Errors & retries.
Highlights
Two commands return snippets. expandai fetch --highlights makes a new Fetch and highlights it in the same request. expandai snapshots get highlights a Snapshot you already have. How they differ, and how to tune --max-results and --min-score, is on Two ways to highlight.
With --highlights, the CLI always calls POST /v1/fetch/json, whatever --format says. --format text prints each snippet with its source, its score, and a citation link. --format json prints the whole JSON object, with the snippets under data.highlights.snippets and a citationUrl added to each one.
Note
Zero snippets is an error on the command line. --format text fails with No snippets were returned. Lower --min-score and try again.
expandai snapshots get <snapshotId>
Read the public Snapshot catalog without authentication. The default text output is Markdown; --format json returns the catalog as JSON.
expandai snapshots get <snapshotId>
Add --highlights "query" to get relevant passages. This requires authentication and costs one Highlights credit.
expandai snapshots get <snapshotId> --highlights <query>
Print Snapshot Highlights for a page you already fetched. The CLI calls POST /v1/snapshots/<snapshotId>/highlights, so the page is not fetched again.
expandai snapshots get 019c0000-0000-7000-8000-000000000020 --highlights "retry policy"
Argument
Definition
snapshotId
meta.snapshotId from an earlier --format json Fetch, or the Snapshot ID in the note a hook prepends.
Option
Definition
Default
--highlights
Query for relevant passages in the Snapshot.
None
--format
text prints the snippets. json prints the JSON object.
text
Snapshot Highlights uses the Main Markdown and State JSON. The Appendix is not searched from the CLI.
Warning
Pass meta.snapshotId, the capture's own ID. meta.resources.snapshotId is the public Snapshot ID and returns 404 FetchSnapshotHighlightsNotFound. See Two IDs.
Appendix
expandai appendix <snapshotId>
Read the Appendix of a page you already fetched. Where Fetch moved navigation, a footer, or related links out of the Main Markdown, the Markdown text carries a marker on its own line:
[appendix omitted: 14 links · ~320 tokens] {612}
{612} is the evidence ID of the first omitted block. Pass it with --id to read that block, or leave --id off for the whole Appendix.
meta.snapshotId from a --format json Fetch, or the capture URL from the playground: frontmatter line of Markdown text.
Option
Definition
Default
--id
The evidence ID from a marker.
The whole Appendix
--format
text prints a citation line, then the Markdown. json prints snapshotId, evidenceId, playground, , and .
The command reads the public Snapshot routes on the Playground host. It needs no API key and starts no new Fetch.
Note
A bare ID is resolved against EXPAND_PLAYGROUND_HOST, which defaults to the production Playground. Pass the capture URL when the Snapshot came from another stack.
Auth and configuration
Signing in versus API keys, and how each surface sends the key, is on Authentication.
expandai login
Store credentials for the CLI, the local MCP server, and the hooks.
expandai login
In a terminal the command asks how you want to authenticate. Browser Login opens a page where you approve the device. API Key prompts for a key and never shows it in your shell history. When credentials are already stored, the command asks before replacing them.
When no terminal is attached, or a coding agent is running the command, only expandai login --json is accepted. It starts or resumes one device authorization and prints one JSON result. status is authorization_required, with authorization.url and authorization.userCode to show the user, completed, or error. Run the same command again after the user approves.
expandai whoami
Show the account, organization, and credential the CLI is using.
expandai whoamiexpandai whoami --format json
Option
Definition
Default
--format
text prints a short status. json prints authenticated, user, organization, and authentication. When not signed in, mode is preview, unauthenticated, credential-rejected, or identity-unavailable.
With no stored credentials, whoami reports Anonymous (free preview), and every Fetch runs against a free preview session until you sign in.
expandai logout
Clear stored credentials.
expandai logout
In a terminal the command also offers to remove installed hooks, Skills, and MCP entries. Outside a terminal it only clears credentials. Run expandai uninstall for the rest.
Environment and config
Name
Definition
EXPAND_API_KEY
An API key. A stored login from expandai login or expandai init takes precedence over it, unless the login was issued by a different API origin. The CLI logs a warning either way.
EXPAND_API_URL
The API origin. Overrides the config file.
EXPAND_APP_URL
The web app origin the CLI points agents at. Default .
Credentials and settings are stored in $XDG_CONFIG_HOME/expandai/config.json, which is ~/.config/expandai/config.json on every platform when XDG_CONFIG_HOME is unset.
Agent setup
These commands wire Expand into a coding agent. The hosted MCP server needs none of them. See Connect your agent (MCP) for that path, and CLI: Skill & hooks for what the local setup adds.
Every install takes a <host> and a <scope>. Hosts are claude-code, cursor, opencode, codex, and fx. Scope is global, for every session on the machine, or project, which writes into the current working directory. Run project installs from the project root.
Note
The CLI shows a smaller command set when a coding agent runs it. When stdout is not a terminal, or CLAUDECODE, CURSOR_TRACE_ID, or CODEX_RUN_ID is set, mcp install, mcp uninstall, skill, hook install, and hook uninstall are hidden, and expandai init --json is the setup command. EXPANDAI_CLI_CONTEXT=human or =agent overrides the detection.
expandai init
Sign in and configure the coding agents on this machine in one step.
expandai initexpandai init --detectexpandai init --harnesses claude-code,cursor --scope global
Option
Definition
Default
--detect
Print the agents setup would configure, and change nothing.
Off
--harnesses
Comma-separated agents to configure, from claude-code, cursor, opencode, codex, fx.
In a terminal, init asks for the scope, shows the detected agents with all of them selected, and, when no usable credentials are stored, prints a URL and a code to approve in the browser. What each agent receives:
Agent
What init configures
Claude Code
The Expand Skill and the MCP server. Nothing is written to settings.json.
Cursor
The Expand Skill and the MCP server.
Codex
The Expand Skill and the MCP server.
OpenCode
The Expand Skill, the MCP server, and the web-fetch hook.
With --json, a sign-in that needs the browser returns status: "authorization_required" with authorization.url and authorization.userCode. Run the same command again after the user approves. Nothing is pasted back.
expandai status
Report what is configured for one agent and scope. The command reads and writes nothing.
expandai status --harness claude-code --scope globalexpandai status --harness opencode --scope project --json
Option
Definition
Default
--harness
claude-code, cursor, opencode, codex, or fx.
Asked in a terminal. Required with --json.
--scope
or .
The text output lists the auth state, any pending authorization, whether the Skill and the MCP server are configured, the web-fetch hook for OpenCode, and whether the agent needs a restart to pick the configuration up.
expandai mcp run
Run the Expand MCP server over stdio.
expandai mcp runexpandai mcp run --docs
Option
Definition
Default
--docs
Also serve the expand://about and expand://start resources.
Off
Agents launch this command from their MCP config. You rarely run it by hand. It uses the credentials from expandai login, so no key is written into the agent's config. The tools are on MCP tools & resources.
expandai mcp install <host> <scope>
Register the MCP server in one agent's config. expandai mcp uninstall <host> <scope> removes it.
The entry is named expandai and runs expandai mcp run. When expandai is not on PATH at install time, the entry runs npx -y expandai mcp run instead.
In project scope, fx and Claude Code read the same .mcp.json. fx uses an entry Claude Code wrote, and uninstalling Claude Code's while fx is still set up in the project leaves fx an entry of its own. fx asks you to approve a project's servers before it connects them. fx mcp trust approve expandai approves Expand's ahead of time.
expandai skill install <host> <scope>
Copy the Expand Skill into one agent's skills directory. expandai skill uninstall <host> <scope> removes it.
Commit a project-scoped Skill only when you want it enabled for everyone who clones the repository.
expandai hook install <host> <scope>
Install the Expand Skill, register the MCP server, and install the web-fetch hook for one agent, in that order. Hosts are claude-code and opencode. expandai hook uninstall <host> <scope> removes the hook and the MCP entry.
expandai hook claude-code and expandai hook opencode
The protocol runners the hooks call. Each reads one JSON payload from stdin, fetches the URL in it through Expand, and writes the result to stdout.
expandai hook opencode
Agents run these when a hook fires. You do not call them yourself.
Cleanup
expandai uninstall [target] [host] [scope]
Remove hooks, Skills, and MCP entries.
expandai uninstallexpandai uninstall mcp codex projectexpandai uninstall skill claude-code global
Argument
Definition
Default
target
all, hook, skill, or mcp.
all
host
claude-code, , , , or .
Warning
Project-scoped files are looked up from the current working directory. Run uninstall from the same project root you installed from, or the files are not found.
Telemetry
The CLI sends anonymous usage events, and says so the first time you run it in a terminal.
EXPANDAI_NO_TELEMETRY=1 or DO_NOT_TRACK=1 turns it off without changing the config file.
Crawl
expandai crawl <url> <directory> crawls a site into a folder of Markdown files you can resume. expandai sync [url] [directory] creates or upgrades a synchronized crawl and keeps the folder current. Its subcommands are sync status, sync run, sync install, which installs a systemd user timer on Linux or a launchd agent on macOS, and sync uninstall.
Both commands exit 0 when nothing changed, 3 when at least one page changed, 2 on a usage error, and 1 on any other failure. expandai crawl --help and expandai sync --help list every flag. What a crawl is, and how it finds pages, is on Crawl and WebSync.
Next steps
CLI: Skill & hooks: what the local setup adds, and what the Skill teaches an agent.