# Quickstart (https://staging.expand.ai/docs/get-started/quickstart)



## Run Fetch in seconds. [#run-fetch-in-seconds]

Fetch a live page yourself, or give Expand to your coding agent. The human path starts with one command. The agent path starts with your harness integration.

<div className="my-8 grid gap-4 lg:grid-cols-2">
  <div className="rounded-lg border border-primary/30 bg-background-dark p-5">
    <h3 className="font-semibold text-contrast-high text-lg">
      Human quickstart
    </h3>

    <p className="mt-2 text-contrast-medium text-sm">
      Run one command in your terminal. Prints agent-ready Markdown for a live page, usually in seconds.
    </p>

    <p className="mt-3 text-contrast-medium text-sm">
      <a href="#run-once-with-npx">Run once</a>

       · 

      <a href="#install-globally">Install globally</a>

       · 

      <a href="#typescript-sdk">Use the SDK</a>

       · 

      <a href="#direct-api">Call the API</a>
    </p>
  </div>

  <div className="rounded-lg border border-contrast-lowest bg-background p-5">
    <h3 className="font-semibold text-contrast-high text-lg">
      Agent quickstart
    </h3>

    <p className="mt-2 text-contrast-medium text-sm">
      Give Fetch to Claude Code, Codex, Cursor, or OpenCode, then verify with one prompt.
    </p>

    <p className="mt-3 text-contrast-medium text-sm">
      <a href="/docs/agent-quickstarts">Agent Quickstarts</a>

       · 

      <a href="/docs/agent-quickstarts/expand-skill">Expand Skill</a>

       · 

      <a href="#agent-path">Verify setup</a>
    </p>
  </div>
</div>

The primary human command:

```bash
npx expandai fetch https://news.ycombinator.com
```

This prints agent-ready Markdown for a live page. No project, no config.

> The short `expandai` CLI package is pending publish. Until it is live, run `npx @expandai/cli fetch https://news.ycombinator.com`. The `npx expandai ...` form above is the target command.

The primary agent prompt:

```txt
Use Expand to fetch https://news.ycombinator.com.
Show me the first 10 lines of Markdown and confirm the Fetch succeeded.
```

If your agent does not have Expand yet, point it at setup first:

```txt
Read /start.md or the Expand Agent Quickstart for your harness, install the recommended integration, then run the verification Fetch.
```

## Human path [#human-path]

### Run once with npx [#run-once-with-npx]

```bash
npx expandai fetch https://news.ycombinator.com
```

* No global install required.
* Prints Markdown by default.
* Best for trying Fetch once.

### Install globally [#install-globally]

Once `expandai` is published under the short name:

```bash
npm install -g expandai
expandai fetch https://news.ycombinator.com
```

If the package is still scoped at install time, use the scoped name with the same binary:

```bash
npm install -g @expandai/cli
expandai fetch https://news.ycombinator.com
```

### Authenticate when needed [#authenticate-when-needed]

Log in once and the CLI reuses your local session:

```bash
expandai login
expandai whoami
```

For CI, servers, and non-interactive runs, set an API key instead. The CLI, SDKs, and direct API all read `EXPAND_API_KEY`:

```bash
export EXPAND_API_KEY="xpnd_..."
```

> Keep API keys server-side. Raw keys are shown only once after creation.

## Expected output [#expected-output]

Markdown mode prints the readable page body. A Hacker News fetch starts like this:

```md
# Hacker News

1. Example story title
2. Another story title
...
```

When you want metadata and structured signal alongside the Markdown, request JSON mode:

```bash
expandai fetch https://news.ycombinator.com --format json
```

Object-mode JSON carries:

* `markdown` — Main Markdown for the page;
* State JSON — included in the response when it is useful and fits, addressable by reference when it is too large;
* `meta.snapshotId` — the reusable snapshot handle for replay and follow-up Highlights;
* metadata and evidence/source handles where returned.

Markdown mode does not print a `snapshotId`. Use `--format json` or an SDK `fetchJson` call when you need the snapshot handle.

## API and SDK paths [#api-and-sdk-paths]

These are secondary to the CLI for a first run, but they are the path into application code.

### Direct API [#direct-api]

```bash
curl -X POST https://api.expand.ai/v1/fetch \
  -H "x-expand-api-key: $EXPAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://news.ycombinator.com"}'
```

* `POST /v1/fetch` returns Markdown.
* `POST /v1/fetch/json` returns object-mode JSON with Main Markdown, State JSON, and metadata.
* Authored cURL examples use the `x-expand-api-key` header. See [API Reference](/api-reference) and [Output Model](/docs/fetch/output-model) for exact schemas.

### TypeScript SDK [#typescript-sdk]

Install `@expandai/sdk`. The client reads `EXPAND_API_KEY` from the environment.

```ts
import { ExpandClient } from "@expandai/sdk"

const client = new ExpandClient()

const markdown = await client.fetch({ url: "https://news.ycombinator.com" })
console.log(markdown)
```

Use `client.fetchJson({ url })` when you need Main Markdown, State JSON, and `meta.snapshotId` together. See the [TypeScript SDK](/docs/reference/typescript-sdk) reference.

### Python SDK [#python-sdk]

Install `expandai` and set `EXPAND_API_KEY`. The client opens as a context manager.

```python
from expandai import Expand, FetchParams, FetchJsonParams

with Expand() as expand:
    markdown = expand.fetch(FetchParams(url="https://news.ycombinator.com"))
    print(markdown)
```

Use `expand.fetch_json(FetchJsonParams(url=...))` for Main Markdown plus State JSON and `meta.snapshot_id`. See the [Python SDK](/docs/reference/python-sdk) reference.

## Agent path [#agent-path]

The fastest way to give an agent web context is its native setup, not a paste. Pick your harness, install once, then verify.

| Agent                                              | First path               |
| -------------------------------------------------- | ------------------------ |
| [Claude Code](/docs/agent-quickstarts/claude-code) | Hook — also installs MCP |
| [Codex](/docs/agent-quickstarts/codex)             | Skill + MCP              |
| [Cursor](/docs/agent-quickstarts/cursor)           | Skill + MCP              |
| [OpenCode](/docs/agent-quickstarts/opencode)       | Hook — also installs MCP |

Hooks are available for Claude Code and OpenCode. Skill and MCP setup accept `claude-code`, `cursor`, `opencode`, and `codex`. Pi, Hermes, and OpenClaw are skill-based — set them up from [Skill-Based Agents](/docs/agent-quickstarts/skill-based-agents).

After setup, confirm the integration with one prompt:

```txt
Use Expand to fetch https://news.ycombinator.com.
Show me the first 10 lines of Markdown and confirm the Fetch succeeded.
```

## Troubleshooting [#troubleshooting]

* `npx expandai` not found: the short package is pending publish — use `npx @expandai/cli fetch ...` or install globally.
* CLI not authenticated: run `expandai login`, then `expandai whoami` to confirm.
* API key missing: set `EXPAND_API_KEY`, or send the `x-expand-api-key` header on direct API calls.
* Empty or blocked output: try another URL, then see [Browser Behavior](/docs/fetch/browser-behavior).
* Need a structured response: use `--format json` on the CLI or `POST /v1/fetch/json`.
* Need links, State JSON, or evidence: see [Output Model](/docs/fetch/output-model), [Include Options](/docs/fetch/include-options), and [How Fetch Works](/docs/fetch/how-fetch-works).

## Next steps [#next-steps]

* [Ways to Use Expand](/docs/get-started/ways-to-use-expand): choose agent, CLI, SDK, API, or Playground.
* [Agent Quickstarts](/docs/agent-quickstarts): configure your harness.
* [CLI Commands](/docs/reference/cli-commands): learn every CLI command.
* [TypeScript SDK](/docs/reference/typescript-sdk) and [Python SDK](/docs/reference/python-sdk): integrate in application code.
* [How Fetch Works](/docs/fetch/how-fetch-works): learn Main Markdown, State JSON, Appendix, Highlights, and evidence.
* [API Reference](/api-reference): the exact endpoint contract.