> ## Documentation Index
> Fetch the complete documentation index at: https://kagi.micr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# extract

> Complete reference for the kagi extract command - fetch a page's full content as markdown using Kagi's Extract API.

# `kagi extract`

Extract the readable content of a web page as markdown using Kagi's Extract API.

## Synopsis

```bash theme={null}
kagi extract <URL> [--format markdown|json|compact]
kagi extract --filter
```

## Description

The `kagi extract` command sends one HTTPS URL to Kagi's v1 Extract API and prints the extracted page markdown to stdout by default. It is useful when a search result, article, or documentation page needs full-page text instead of a search snippet.

The command uses JSON mode internally because that is the stable envelope returned by the API, then prints the first page's `markdown` field. Use `--format json` or `--format compact` to print the full response envelope, including retained link metadata when Kagi returns it. If Kagi returns no page markdown, the CLI reports the Extract API error details and trace id when available.

Use `--filter` for pipelines that already have one URL per line. Filter mode ignores the single-URL markdown default and prints one compact JSON record per input line in the same order. Successful records include the Extract API response under `response`. Failed records include an `error` envelope on stdout and the command exits nonzero after all inputs are processed.

## Authentication

**Required:** `KAGI_API_KEY`

Extract is part of Kagi's current `/api/v1` paid API surface, uses `Bearer` auth, and consumes API credit per request.

## Arguments

### `<URL>` (Required)

The HTTPS URL of the page to extract.

```bash theme={null}
kagi extract "https://example.com/article"
```

Only `https://` URLs with a valid host are accepted.

Omit `<URL>` when using `--filter`.

### `--filter`

Read one URL per stdin line and print JSONL records.

```bash theme={null}
kagi search "rust release notes" --template '{{url}}' | kagi extract --filter
```

### `--format <FORMAT>`

Output format. Default: `markdown`.

Supported values:

* `markdown` - print the first page's markdown content only
* `json` - print the full Extract API response envelope
* `compact` - print the full response envelope as compact JSON

## Output

The command prints markdown directly:

```markdown theme={null}
# Article title

Extracted page content...
```

With `--format json`, the command prints the full response envelope:

```json theme={null}
{
  "meta": {
    "trace": "trace-1",
    "node": "test",
    "ms": 12
  },
  "data": [
    {
      "url": "https://example.com/article",
      "markdown": "# Article title\n\nExtracted page content...",
      "links": [
        {
          "text": "Source",
          "url": "https://example.com/"
        }
      ]
    }
  ]
}
```

With `--filter`, stdout is JSONL:

```jsonl theme={null}
{"url":"https://example.com/article","ok":true,"response":{"meta":{"trace":"trace-1","node":"test","ms":12},"data":[{"url":"https://example.com/article","markdown":"# Article title\n\nExtracted page content...","links":[]}]}}
{"url":"http://example.com/bad","ok":false,"error":{"code":"configuration_error","category":"configuration","retryable":false,"message":"configuration error: extract URL must use the https scheme","suggested_commands":[],"docs_url":"https://kagi.micr.dev/reference/error-reference"}}
```

## Examples

### Save an Article

```bash theme={null}
kagi extract "https://example.com/article" > article.md
```

### Pipe into Another Tool

```bash theme={null}
kagi extract "https://example.com/article" | sed -n '1,80p'
```

### Inspect Retained Links

```bash theme={null}
kagi extract "https://example.com/article" --format json | jq '.data[0].links'
```

### Extract Search Results

```bash theme={null}
kagi search "rust async cancellation" --template '{{url}}' | kagi extract --filter > pages.jsonl
```

## Exit Codes

| Code | Meaning                                                                               |
| ---- | ------------------------------------------------------------------------------------- |
| 0    | Success - markdown extracted, or every `--filter` input produced an `ok: true` record |
| 1    | Error - see stderr; `--filter` may still have written per-input records to stdout     |

Common errors:

* Missing API key
* Non-HTTPS or invalid URL
* Insufficient API credit
* Kagi returns no extractable content
* Network error