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

# Data export

> Export your knowledge base as JSONL, CSV, or Parquet.

KiwiFS can export your entire knowledge base (or a subset of it) as JSONL, CSV, or Parquet. You can export from the CLI or the REST API.

## Formats

<Tabs>
  <Tab title="JSONL">
    Each line is a JSON object representing one file. Fields come from frontmatter.

    ```json theme={null}
    {"path":"concepts/auth.md","title":"Authentication","status":"published","updated":"2026-04-20T10:00:00Z"}
    ```

    With `--include-content`, each object includes the full markdown body.

    ```json theme={null}
    {"path":"concepts/auth.md","title":"Authentication","status":"published","content":"# Authentication\n\nOverview of auth mechanisms.\n"}
    ```

    With `--include-links`, each object includes link data.

    ```json theme={null}
    {"path":"concepts/auth.md","title":"Authentication","outgoing_links":["concepts/oauth.md","concepts/jwt.md"],"incoming_links":["guides/security.md"]}
    ```

    With `--include-embeddings`, each object includes a vector embedding array. A `.schema.json` sidecar file is also written alongside the output file, describing the embedding model and dimensions.

    ```json theme={null}
    {"path":"concepts/auth.md","title":"Authentication","embedding":[0.0123,-0.0456,0.0789]}
    ```
  </Tab>

  <Tab title="Parquet">
    Columnar export for data warehouses and analytics pipelines. Supports the same flags as JSONL (`--include-content`, `--include-links`, `--include-embeddings`, `--path`, `--limit`).

    ```bash theme={null}
    kiwifs export --format parquet --include-content -o knowledge.parquet
    ```
  </Tab>

  <Tab title="CSV">
    Standard CSV with one row per file. The first row contains headers. Specify which frontmatter fields to include with `--columns`.

    ```csv theme={null}
    path,name,status,grade
    students/alice.md,Alice,active,A
    students/bob.md,Bob,active,B+
    students/carol.md,Carol,graduated,A-
    ```
  </Tab>
</Tabs>

## CLI usage

Use the `kiwifs export` command to export from the command line.

<CodeGroup>
  ```bash Export all files as JSONL theme={null}
  kiwifs export --format jsonl --output knowledge.jsonl
  ```

  ```bash Export with full content theme={null}
  kiwifs export --format jsonl --include-content --output full.jsonl
  ```

  ```bash Export a subdirectory as CSV theme={null}
  kiwifs export --format csv --path students/ --columns name,status,grade -o students.csv
  ```

  ```bash Export as Parquet theme={null}
  kiwifs export --format parquet --include-content -o knowledge.parquet
  ```

  ```bash Pipe to jq theme={null}
  kiwifs export --format jsonl | jq '.title'
  ```

  ```bash Include vector embeddings theme={null}
  kiwifs export --format jsonl --include-embeddings -o vectors.jsonl
  ```
</CodeGroup>

### CLI flags

| Flag                   | Short | Default       | Description                                   |
| ---------------------- | ----- | ------------- | --------------------------------------------- |
| `--root`               | `-r`  | `./knowledge` | Knowledge root directory                      |
| `--format`             |       | `jsonl`       | Output format: `jsonl`, `csv`, or `parquet`   |
| `--output`             | `-o`  | stdout        | Output file path                              |
| `--path`               |       |               | Scope export to a subdirectory                |
| `--columns`            |       |               | Comma-separated frontmatter fields to include |
| `--include-content`    |       | `false`       | Include the full markdown body                |
| `--include-links`      |       | `false`       | Include outgoing and incoming link arrays     |
| `--include-embeddings` |       | `false`       | Include vector embeddings                     |
| `--limit`              |       | `0`           | Max files to export (0 = unlimited)           |

## REST API

Export your knowledge base over HTTP using the `/api/kiwi/export` endpoint.

<CodeGroup>
  ```bash JSONL with content theme={null}
  curl "http://localhost:3333/api/kiwi/export?format=jsonl&include-content=true" \
    -o knowledge.jsonl
  ```

  ```bash CSV with specific columns theme={null}
  curl "http://localhost:3333/api/kiwi/export?format=csv&columns=name,status&path=students/" \
    -o students.csv
  ```

  ```bash With API key auth theme={null}
  curl "http://localhost:3333/api/kiwi/export?format=jsonl" \
    -H "Authorization: Bearer my-api-key" \
    -o knowledge.jsonl
  ```
</CodeGroup>

### Query parameters

| Parameter            | Default | Description                                 |
| -------------------- | ------- | ------------------------------------------- |
| `format`             | `jsonl` | Output format: `jsonl`, `csv`, or `parquet` |
| `path`               |         | Scope to a subdirectory                     |
| `columns`            |         | Comma-separated frontmatter fields          |
| `include-content`    | `false` | Include markdown body                       |
| `include-links`      | `false` | Include link arrays                         |
| `include-embeddings` | `false` | Include vector embeddings                   |
| `limit`              | `0`     | Max files (0 = unlimited)                   |

The response streams as `application/x-ndjson` (JSONL) or `text/csv` (CSV) with chunked transfer encoding. You can pipe the response directly into downstream tools.

## Embeddings sidecar

When you export with `--include-embeddings`, KiwiFS writes a `.schema.json` sidecar file next to the output file. This file describes the embedding model used and the vector dimensions.

```json vectors.schema.json theme={null}
{
  "embedding_model": "text-embedding-3-small",
  "dimensions": 1536,
  "distance_metric": "cosine"
}
```

<Note>
  Embeddings are only available if you have configured a vector search provider (such as pgvector with an OpenAI API key).
</Note>

## Common recipes

<AccordionGroup>
  <Accordion title="Back up metadata to git">
    Export frontmatter as JSONL and commit it alongside your knowledge base for a searchable metadata snapshot.

    ```bash theme={null}
    kiwifs export --format jsonl -o .kiwi/metadata.jsonl
    cd knowledge && git add .kiwi/metadata.jsonl && git commit -m "Update metadata export"
    ```
  </Accordion>

  <Accordion title="Build a static search index">
    Export with content and embeddings, then feed the output into your static site search pipeline.

    ```bash theme={null}
    kiwifs export --format jsonl --include-content --include-embeddings -o search-index.jsonl
    ```
  </Accordion>

  <Accordion title="Sync to a data warehouse">
    Export as CSV and load into your warehouse using standard ETL tools.

    ```bash theme={null}
    kiwifs export --format csv --columns title,status,updated,author -o export.csv
    # Load into your warehouse
    bq load --source_format=CSV mydataset.knowledge export.csv
    ```
  </Accordion>

  <Accordion title="Filter with jq">
    Pipe JSONL output to `jq` for ad-hoc filtering and transformation.

    ```bash theme={null}
    # Find all draft documents
    kiwifs export --format jsonl | jq 'select(.status == "draft")'

    # Extract just titles and paths
    kiwifs export --format jsonl | jq '{path, title}'

    # Count documents by status
    kiwifs export --format jsonl | jq -s 'group_by(.status) | map({status: .[0].status, count: length})'
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  For large knowledge bases, use `--path` to scope the export to a subdirectory and `--limit` to cap the number of files. This keeps export times predictable.
</Tip>

## Document export (PDF, HTML, slides)

To render markdown into PDF, HTML, slide decks, or static sites, use [Document export](/export/documents) (`POST /api/kiwi/export/document` or MCP `kiwi_export_document`).