CLI Commands

Jump to: Fetch · Highlights · Auth · Agent setup · Cleanup

Command index

Commands are grouped by job. Each one is copyable as written.

Config is set through environment variables (EXPAND_API_KEY, EXPAND_API_URL) and the local config file under XDG_CONFIG_HOME. See Auth and configuration.

Batched Fetch has no CLI command today. Start and poll batched runs through the API or SDKs. See Batched Fetch.

Fetch content

expandai fetch <url>

Fetch a rendered web page and print agent-ready Markdown.

Output. Default text output prints Markdown to stdout. --format json prints structured Fetch output. With --search, text mode prints Highlights snippets instead of the full page.

The CLI does not expose Include Options through an --include flag today, and --format accepts only text or json, not markdown.

Related: Fetch Overview · Output Model · Include Options · API Reference

expandai fetch <url> --format json

Fetch a page and print structured JSON instead of text Markdown.

JSON output is what you want when a script needs fields — metadata, Markdown, and State JSON when present — rather than terminal Markdown. State JSON is usually included in the main content; large state may be returned by reference instead.

This is not equivalent to every API Include Options combination. The CLI does not expose the nested include controls that the API offers; for that level of control, call the API directly. See Include Options.

Highlights

--search and expandai search both return Highlights — the most relevant snippets of a page for a query. text/json Both accept --max-results (1–50, default 5) and --min-score (0–1, default 0.6).

expandai fetch <url> --search <query>

Fetch a page and return the most relevant Highlights snippets for a query.

This performs a new Fetch, then runs the query against the captured page. It uses inline Fetch JSON Mode with search in the request payload — not the snapshot-search endpoint — so it always recaptures the URL.

Text output includes source and score headers plus an auditable citation link for each snippet. JSON output follows the API result shape. Default corpus behavior is covered on the Highlights page.

Related: Highlights · Output Model · Playground & Replay · fetch.fetchJson

expandai search <snapshotId> <query>

Search an existing snapshot without fetching the page again.

Use search for snapshot reuse: it queries a page you already captured and skips the network round trip. If you do not have a snapshotId yet, run expandai fetch <url> --search <query> instead.

Related: Highlights · Playground & Replay · fetch.fetchSearch (/v1/fetch/search)

Auth and configuration

expandai login

Store local credentials for CLI and local integration use. interactive

The command is interactive and supports two paths: browser login and API-key login. API-key auth is the normal production and server path. Credentials are written to the local Expand CLI config file (see Environment and config). Do not paste API keys into shell history; let login prompt for them.

expandai whoami

Check which Expand account or credential the CLI is using.

This is the first command to run when Fetch, MCP, skills, or hooks fail because of auth. If whoami shows the wrong account or no credential, run expandai login.

expandai logout

Clear local stored Expand credentials.

Environment and config

Authored cURL examples authenticate with the API-key header, not bearer:

Agent setup

These commands wire Expand into local agent hosts: MCP config, the Expand Skill, and native-fetch hooks. The per-host quickstarts own the recommended setup and verification flow — Claude Code, Cursor, Codex, and OpenCode. agent setup

Install and uninstall commands take an explicit <scope> of global or project. Project scope writes files into the current working directory, so run these from the project root you want them in.

expandai mcp run [--docs]

Run the local Expand MCP server over stdio.

MCP clients and generated MCP config launch this command; you rarely run it by hand. Plain mcp run exposes the Fetch tools. --docs additionally exposes Expand docs resources. First-class installers do not enable --docs by default. Full tool schemas live in MCP Tools & Resources; there is no hosted or remote Expand MCP server today.

expandai mcp install <host> <scope>

Install Expand MCP config for a supported local agent host.

Hosts: claude-code, cursor, opencode, codex. Scopes: global, project.

expandai mcp uninstall <host> <scope>

Remove Expand MCP config for a supported host and scope.

expandai skill install <host> <scope>

Install the Expand Skill for a supported agent host.

Hosts: claude-code, cursor, opencode, codex. Scopes: global, project.

Skills teach agents how to use Expand. Project scope writes skill files into the current project — commit them only if you want the skill enabled for collaborators. The command requires an explicit scope; it does not default to project. Detailed behavior lives on the Expand Skill page.

expandai skill uninstall <host> <scope>

Remove the Expand Skill for a host and scope.

expandai hook install <host> <scope>

Install an Expand hook for hosts that can route native web-fetch behavior through Expand.

Hosts: claude-code, opencode. Scopes: global, project.

Hook behavior is host-specific. The host pages own the full setup and verification flow.

expandai hook uninstall <host> <scope>

Remove an Expand hook for a host and scope.

expandai hook claude-code and expandai hook opencode

Runtime commands invoked by the Claude Code and OpenCode hook integrations. integration runtime

These are integration-facing, not primary user commands. Most users should hook install or hook uninstall and never call them directly — the host invokes them when a hook fires.

Cleanup

expandai uninstall [target] [host] [scope]

Remove Expand integration files across hooks, skills, and MCP config.

• target selects a surface such as all, hook, skill, or MCP.
• host narrows cleanup to a supported host.
• scope narrows cleanup to global or project files.
• With no arguments, the command uses broad cleanup defaults.

Project-scoped cleanup depends on the current working directory. Run cleanup from the same project root you used during installation, or it will not find the files to remove.

Related pages