> ## 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.

# File imports

> Import data from CSV, JSON, JSONL, YAML, and Excel files into KiwiFS.

KiwiFS can import structured data from local files, converting each record into a markdown page with frontmatter.

## CSV

```bash theme={null}
kiwifs import --from csv \
  --file data.csv \
  --prefix people/ \
  --root ./knowledge
```

| Flag          | Description                       |
| ------------- | --------------------------------- |
| `--file`      | Path to CSV file (required)       |
| `--columns`   | Comma-separated fields to include |
| `--id-column` | Column to use as filename         |
| `--prefix`    | Path prefix in KiwiFS             |
| `--limit`     | Max records to import             |
| `--dry-run`   | Preview without writing           |

The first row of the CSV is treated as column headers. Each subsequent row becomes a markdown file.

### Example

Given a CSV:

```csv theme={null}
name,email,department
Jane Doe,jane@example.com,Engineering
Bob Smith,bob@example.com,Product
```

After import:

```markdown theme={null}
---
_imported_at: "2026-04-25T18:46:15Z"
_source: data.csv
name: Jane Doe
email: jane@example.com
department: Engineering
---

# Jane Doe

> Auto-imported from data.csv
```

## JSON

```bash theme={null}
kiwifs import --from json \
  --file data.json \
  --prefix items/
```

Expects a JSON file containing an array of objects:

```json theme={null}
[
  {"name": "Item A", "status": "active"},
  {"name": "Item B", "status": "draft"}
]
```

## JSONL

```bash theme={null}
kiwifs import --from jsonl \
  --file data.jsonl \
  --prefix items/
```

Each line is a JSON object:

```jsonl theme={null}
{"name": "Item A", "status": "active"}
{"name": "Item B", "status": "draft"}
```

JSONL is ideal for large datasets — KiwiFS streams lines without loading the entire file into memory.

## YAML

```bash theme={null}
kiwifs import --from yaml \
  --file data.yaml \
  --prefix items/
```

Expects a YAML file containing a list of mappings:

```yaml theme={null}
- name: Item A
  status: active
- name: Item B
  status: draft
```

Each mapping becomes a markdown page with its keys as frontmatter fields.

## Excel

```bash theme={null}
kiwifs import --from excel \
  --file data.xlsx \
  --prefix records/ \
  --sheet "Sheet1"
```

| Flag          | Description                                        |
| ------------- | -------------------------------------------------- |
| `--file`      | Path to `.xlsx` file (required)                    |
| `--sheet`     | Sheet name to import (defaults to the first sheet) |
| `--columns`   | Comma-separated columns to include                 |
| `--id-column` | Column to use as filename                          |
| `--prefix`    | Path prefix in KiwiFS                              |
| `--limit`     | Max rows to import                                 |
| `--dry-run`   | Preview without writing                            |

The first row is treated as column headers.

## MCP usage

File imports are available via the `kiwi_import` MCP tool:

```json theme={null}
{
  "tool": "kiwi_import",
  "arguments": {
    "from": "csv",
    "file": "/path/to/data.csv",
    "prefix": "people/"
  }
}
```

<Note>
  MCP file imports require local mode (`kiwifs mcp --root`). The file path must be accessible to the KiwiFS process.
</Note>

## Column filtering

Use `--columns` to import only specific fields:

```bash theme={null}
kiwifs import --from csv --file data.csv --columns "name,email,status" --prefix people/
```

Fields not listed are excluded from the frontmatter.