Expand AI logo
DocsDocs
Glow Active
API Reference
Login

Documentation

Get Started

OverviewWhy ExpandQuickstartWays to Use Expand

Agent Quickstarts

OverviewExpand SkillClaude CodeCursorCodexOpenCodeSkill-Based AgentsOther MCP Clients

Fetch

OverviewHow Fetch WorksOutput ModelInclude OptionsBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

API ReferenceCLI CommandsMCP Tools & ResourcesTypeScript SDKPython SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

start.mdllms.txtllms-full.txtDocs as Markdown
Browse docs

Get Started

OverviewWhy ExpandQuickstartWays to Use Expand

Agent Quickstarts

OverviewExpand SkillClaude CodeCursorCodexOpenCodeSkill-Based AgentsOther MCP Clients

Fetch

OverviewHow Fetch WorksOutput ModelInclude OptionsBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

API ReferenceCLI CommandsMCP Tools & ResourcesTypeScript SDKPython SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

start.mdllms.txtllms-full.txtDocs as Markdown

Skill-Based Agents

Use the Expand Skill with Pi, Hermes, OpenClaw, and other instruction-based agents.

Set up Expand for an agent that has no first-class installer yet. If your agent can read a SKILL.md, install reusable instructions, or follow a setup prompt, it can use Expand through the bundled Skill or MCP.

Pi, Hermes, OpenClaw, and other skill-based agents do not currently have dedicated expandai skill install commands. Use the Expand Skill model below, or configure MCP if your agent supports tools.

Install the Expand Skill

Give the agent the SKILL.md body so it knows when to fetch and how to cite.

Configure MCP instead

Wire Expand as native tools if your agent can call MCP.

Read setup prompt

Hand the agent the machine-readable prompt and let it pick the path.

Each named agent below carries a No native installer yet badge. These are manual setup paths, not first-class CLI support.

Pi

No native installer yet

Use the Expand Skill if Pi can install or read a SKILL.md. Otherwise hand it /start.md. Use the Skill.

Hermes

No native installer yet

Use reusable instructions first, then add MCP if Hermes supports native tools. Use the Skill.

OpenClaw

No native installer yet

The Skill gives behavior guidance; MCP gives native tool calls. Compare Skill and MCP.

Other skill-based agent

Verify the setup with one prompt:

Use Expand to fetch https://news.ycombinator.com.
Confirm you used Expand, show the first 10 lines of Markdown, and include any snapshot or citation link you received.

Recommended setup model

If your agent supports SKILL.md files, copy the Expand Skill into the location your agent expects. If your agent supports MCP tools, configure Expand MCP instead or in addition.

The first-class hosts get this skill from expandai skill install. For an agent without an installer, you place the same skill body yourself: the host decides where the file must live, and Expand provides the content.

Get the skill body

The canonical source is packages/cli/skills/expandai/SKILL.md. Copy the block below into the skill location your agent expects.

---
name: expandai
description: Fetch any URL as clean markdown using the `expandai` CLI. Use when reading documentation, articles, GitHub READMEs, blog posts, or any web page — the output is rendered from the live page so it handles SPAs and bot-protected sites that plain `curl` does not.
---

# expandai

Fetch any URL as clean markdown.

```bash
expandai fetch <url>
```

## When to use

Use

Authenticate the CLI once so the skill's commands work:

expandai login

API keys are for CI, servers, direct API, and other non-interactive use. For local agent setup, prefer expandai login.

Skill vs MCP

NeedUse
Agent can read instructions and run shell commands, but cannot call MCP toolsExpand Skill
Agent supports MCP toolsMCP
Agent supports bothSkill + MCP
Agent cannot install skills or MCP/start.md setup prompt or CLI

Use the Skill when the agent needs instructions for when to fetch, how to reuse Highlights on captured pages, and how to return citations. Use MCP when the agent supports native tools and you want it to call Fetch directly. Use both when the agent supports both.

  • Skill details: Expand Skill
  • MCP config: Other MCP Clients
  • CLI fallback: Quickstart or CLI Commands

First-class alternatives

If you are using Claude Code, Cursor, Codex, or OpenCode, use the first-class setup page instead. Those pages use the installer paths supported by the Expand CLI.

  • Claude Code
  • Cursor
  • Codex
  • OpenCode

Troubleshooting

My agent does not load the skill

Check the skill location your agent expects. Expand only provides the SKILL.md content for non-first-class hosts; the host decides where that file must live.

My agent can run tools

If your agent supports MCP, use Other MCP Clients instead of manually wiring shell commands into the skill.

My agent cannot run shell commands

The Expand Skill teaches CLI usage. If your agent cannot run shell commands, configure MCP or use the direct API/SDK from your application code.

I need an official installer

Official skill installers exist today for Claude Code, Cursor, Codex, and OpenCode. Other agents should use manual skill placement, MCP, or /start.md until a first-class installer exists.

Next steps

  • Agent Quickstarts overview
  • Expand Skill
  • Other MCP Clients
  • start.md
  • CLI Commands
PreviousOpenCode
NextOther MCP Clients

On This Page

Recommended setup modelGet the skill bodySkill vs MCPFirst-class alternativesTroubleshootingMy agent does not load the skillMy agent can run toolsMy agent cannot run shell commandsI need an official installerNext steps
No native installer yet

Put the SKILL.md where the agent loads reusable instructions. Open Skill docs.

`
expandai fetch
`
instead of
`
curl
`
or
`
WebFetch
`
when you need to read web content. It renders the live page (handles JavaScript, SPAs, bot protection) and returns markdown rather than raw HTML.
## Usage
```bash
expandai fetch https://docs.example.com/api
expandai fetch github.com/owner/repo # https:// is added automatically
expandai fetch https://example.com --format json # object-mode { meta, markdown, json }
```
## Output
- Default (`--format text`): full markdown document — pipe to grep, less, or write to a file.
- `--format json`: object-mode response with `meta`, `markdown`, and `json`. The handle for
later searches is `meta.snapshotId`.
## Search a page you already fetched
Every fetch produces a snapshot handle (`meta.snapshotId`). When the WebFetch hook serves a
page, it injects that handle as a note at the top of the markdown. Once a page is captured,
extract specific passages by searching the snapshot by handle — don't fetch the URL again:
```bash
expandai search <snapshotId> "your query" # snippets from the stored snapshot
expandai search <snapshotId> "your query" --format json --max-results 10 --min-score 0.5
```
Agents with the expandai MCP server can call the `fetch_search` tool with the same
`snapshotId` instead.
Use `expandai fetch <url> --search "query"` only for a one-shot fetch+search of a URL you
have not captured yet — it starts a new browser capture. If you already have a `snapshotId`,
prefer `expandai search` (or `fetch_search`), which reuses the existing capture.
## Citations
Search results include enough location data to audit the cited passage. In text output,
`expandai search` and `expandai fetch --search` print a public playground citation link above
each snippet. MCP tool results expose `citationUrl` fields directly.
## Common patterns
```bash
# Read a doc page
expandai fetch https://effect.website/docs/getting-started
# Save to a file
expandai fetch https://example.com > page.md
# Inspect object-mode output, including State JSON when present
expandai fetch https://docs.example.com/api --format json
```
## Failure modes
- Exit code non-zero with `Not authenticated` — the user has not run `expandai login`. Tell them to run it; do not attempt to authenticate yourself.
- Empty markdown output — try `--format json` to inspect the response shape.