File imports

Import CSV, JSON, JSONL, YAML, Excel, BibTeX, and markdown folders into KiwiFS.

File sources read a local file and turn each record into a markdown page. Every source also accepts the common flags: --prefix, --id-column, --columns, --limit, and --dry-run. The default --prefix is the file name without its extension.

Tabular files

CSV

Terminal

kiwifs import --from csv --file people.csv --root ./knowledge

The first row is the header. Each following row becomes a page.

JSON

Terminal

kiwifs import --from json --file items.json --root ./knowledge

The file holds an array of objects.

items.json

[
  { "id": "a", "name": "Item A", "status": "active" },
  { "id": "b", "name": "Item B", "status": "draft" }
]

JSONL

Terminal

kiwifs import --from jsonl --file items.jsonl --root ./knowledge

The file holds one object per line.

items.jsonl

{"id": "a", "name": "Item A", "status": "active"}
{"id": "b", "name": "Item B", "status": "draft"}

YAML

Terminal

kiwifs import --from yaml --file items.yaml --root ./knowledge

The file holds a list of mappings.

items.yaml

- id: a
  name: Item A
  status: active
- id: b
  name: Item B
  status: draft

Excel

Terminal

kiwifs import --from excel --file records.xlsx --sheet "Sheet1" --root ./knowledge

The first row of the sheet is the header. Without --sheet, KiwiFS reads the first sheet.

Flag	Description
--file	Path to the file (required)
--sheet	Sheet name, for excel only

json and jsonl share one reader that detects the format from the first character, so either value works for either file.

File names

For JSON, JSONL, YAML, and Excel, an id or _id field becomes the file name. CSV rows use the row number unless you pass --id-column.

Example

Given this CSV:

people.csv

name,email,department
Jane Doe,[e-mail],Engineering
Bob Smith,[e-mail],Product

kiwifs import --from csv --file people.csv --id-column email writes people/[e-mail]:

people/[e-mail]

---
_imported_at: "2026-10-19T18:46:15Z"
_source: people
_source_id: csv:people:0
department: Engineering
email: [e-mail]
name: Jane Doe
---

# Jane Doe

| Field | Value |
|-------|-------|
| department | Engineering |
| email | [e-mail] |
| name | Jane Doe |

Keep only some fields

Terminal

kiwifs import --from csv --file people.csv --columns "name,email" --prefix people

Fields you don’t list are left out of the frontmatter.

BibTeX

Import a .bib reference file. Each entry becomes a page named after its citation key.

Terminal

kiwifs import --from bibtex --file references.bib --prefix papers

KiwiFS maps common BibTeX fields to frontmatter:

Frontmatter	From
bibtex_key, bibtex_type	Citation key and entry type
title, year	title, year
authors	author, split into a list
venue	journal, booktitle, publisher, or howpublished
tags	keywords, split into a list

Other fields, such as doi, url, and abstract, are copied as-is.

Markdown folders

Copy an existing folder of markdown files into the knowledge base without rewriting their content.

Terminal

kiwifs import --from markdown --path ./old-docs --prefix docs

--path can be a single .md file or a directory. KiwiFS walks subdirectories, keeps each file’s frontmatter and body, and copies non-markdown files such as images next to them. To also convert Obsidian syntax, use --from obsidian instead.

Upload a file over REST

POST /api/kiwi/import/upload takes a multipart upload of up to 256 MB, so the file doesn’t need to be on the server. It accepts csv, json, jsonl, bibtex, and sqlite.

Terminal

curl -X POST http://localhost:3333/api/kiwi/import/upload \
  -F from=csv \
  -F file=@people.csv \
  -F prefix=people \
  -F id_column=email

Field	Description
file	The file to import (required)
from	Source type (required)
prefix	Target folder. Defaults to the uploaded file name.
id_column	Field to use as the file name
table, query	Table or query, for sqlite uploads
field_mappings	JSON array of field mappings, as produced by infer-fields
mode	import (default), preview (first 5 records), or infer-fields

The web UI import wizard uses this endpoint for files you pick from your computer.

From the API or an agent

CSV, JSON, and JSONL also work with POST /api/kiwi/import and the kiwi_import MCP tool. Both read the file path on the machine running KiwiFS.

kiwi_import

{
  "from": "csv",
  "file": "/srv/exports/people.csv",
  "prefix": "people"
}

Related

Import overview

Output format, common flags, and re-import rules.

Ingest documents

Convert PDF, DOCX, and PPTX files into pages.