CLI commands - KiwiFS — Markdown filesystem for agents and teams

All commands use the kiwifs binary. Run kiwifs --help to list available commands, or kiwifs <command> --help for details on a specific command.

Core commands

serve — Start the KiwiFS server

Start the KiwiFS HTTP server and serve your knowledge base.

kiwifs serve [flags]

Flag	Short	Default	Description
`--root`	`-r`	`./knowledge`	Knowledge root directory
`--port`	`-p`	`3333`	HTTP port
`--host`		`0.0.0.0`	Bind address
`--search`		`sqlite`	Search engine: `sqlite` or `grep`
`--versioning`		`git`	Versioning strategy: `git`, `cow`, or `none`
`--auth`		`none`	Auth type: `none`, `apikey`, `perspace`, or `oidc`
`--api-key`			API key (required if `auth=apikey`)
`--oidc-issuer`			OIDC issuer URL
`--oidc-client-id`			OIDC client ID
`--async-commit`		`true`	Enable async batched commits
`--batch-window`		`200`	Async commit batch window in milliseconds
`--batch-max-size`		`50`	Max paths per batch
`--no-watch`		`false`	Disable fsnotify watcher

Protocol flags

Flag	Default	Description
`--nfs`	`false`	Enable userspace NFSv3 server
`--nfs-port`	`2049`	NFS port
`--nfs-allow`		CIDRs allowed to mount NFS
`--s3`	`false`	Enable S3-compatible API
`--s3-port`	`3334`	S3 port
`--webdav`	`false`	Enable WebDAV server
`--webdav-port`	`3335`	WebDAV port
`--space`		Register additional space (repeatable, format: `name=path`)

kiwifs serve --root ./my-docs --port 8080

init — Initialize a knowledge directory

Create a new knowledge directory with an optional template.

kiwifs init [flags]

Flag	Short	Default	Description
`--root`	`-r`	`./knowledge`	Directory to initialize
`--template`		`knowledge`	Template: `knowledge`, `wiki`, `runbook`, `research`, `tasks`, or `blank`

kiwifs init

Templates provide a starter directory structure with sample files. Use blank if you want an empty knowledge base.

mcp — Start MCP server

Start a Model Context Protocol server over stdio transport. Use this to connect KiwiFS to AI agents and LLM tools.

kiwifs mcp [flags]

Flag	Default	Description
`--root`		Knowledge root (in-process mode)
`--remote`		KiwiFS server URL (proxy mode)
`--api-key`		API key for remote server
`--space`	`default`	Space to scope to
`--http`	`false`	Enable Streamable HTTP transport (instead of stdio)
`--port`	`8181`	HTTP port (only with `--http`)

In-process (stdio)
Proxy mode
HTTP transport

Run KiwiFS directly within the MCP server process. Best for local development.

kiwifs mcp --root ./knowledge

Connect to a running KiwiFS server. Best for shared or remote setups.

kiwifs mcp --remote https://kiwi.example.com --api-key my-key

Serve MCP over Streamable HTTP instead of stdio.

kiwifs mcp --root ./knowledge --http --port 8181

mount — FUSE mount a remote KiwiFS

Mount a remote KiwiFS server as a local filesystem using FUSE.

kiwifs mount <mountpoint> [flags]

Flag	Default	Description
`--remote`		Remote KiwiFS server URL (required)
`--api-key`		API key (or `KIWIFS_API_KEY` env)
`--bearer`		Bearer token (or `KIWIFS_BEARER` env)
`--basic-user`		HTTP Basic auth username
`--basic-pass`		HTTP Basic auth password (or `KIWIFS_BASIC_PASS` env)
`--space`	`default`	Space name

kiwifs mount ~/mnt/kiwi --remote https://kiwi.example.com --api-key my-key

FUSE must be installed on your system. On macOS, install macFUSE. On Linux, install fuse3.

Data commands

import — Import data from external sources

Import data from databases, files, or third-party services into your knowledge base.

kiwifs import [flags]

Flag	Short	Default	Description
`--from`			Source type (see list below)
`--root`	`-r`	`./knowledge`	Knowledge root
`--dsn`			Database connection string
`--table`			Table or collection name
`--query`			Custom SQL query
`--file`			Path to data file
`--prefix`			Path prefix in KiwiFS
`--columns`			Comma-separated fields to include
`--id-column`			Column to use as filename
`--limit`			Max records to import
`--dry-run`		`false`	Preview without writing

Supported sources

Category	Sources
Databases	`postgres`, `mysql`, `sqlite`, `mongodb`, `firestore`, `dynamodb`, `redis`, `elasticsearch`
Files	`csv`, `json`, `jsonl`, `yaml`, `excel`
Services	`notion`, `airtable`, `gsheets`, `obsidian`, `confluence`

kiwifs import --from postgres --dsn "postgres://user:pass@localhost/mydb" \
  --table articles --id-column slug --prefix articles/

Use --dry-run first to preview which files will be created before writing anything.

export — Export knowledge base

Export structured data (JSONL, CSV, Parquet) or render markdown into publication formats (PDF, HTML, slides, static site).

kiwifs export [flags]

Data formats

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

Document formats — use --format pdf, html, slides, or site with --path pointing at a file or directory:

Flag	Default	Description
`--theme`		Theme: `paper`, `modern`, `minimal`, `dark`, `presentation`
`--self-contained`	`false`	Embed assets in HTML/PDF output
`--bibliography`		Path to `.bib` or `.json` bibliography
`--csl`		Citation style: `apa`, `ieee`, `chicago`, `vancouver`, `harvard`
`--crossref`	`false`	Enable figure/table/equation cross-references
`--pdf-engine`	auto	PDF engine: `typst` or `xelatex`
`--slide-format`	`html`	Slide output: `html`, `pdf`, or `pptx`
`--site-name`		Static site title (MkDocs)
`--site-url`		Canonical site URL
`--repo-url`		Edit-on-GitHub link for generated site

kiwifs export --format jsonl -o knowledge.jsonl

See Data export and Document export for REST and MCP equivalents.

query — Run a DQL query

Run a Dataview Query Language (DQL) query against your knowledge base.

kiwifs query "<query>" [flags]

Flag	Short	Default	Description
`--root`	`-r`	`./knowledge`	Knowledge root

kiwifs query "TABLE title, status FROM 'concepts' WHERE status = 'draft'"

aggregate — SQL-style aggregation

Run aggregation queries against frontmatter fields.

kiwifs aggregate [flags]

Flag	Short	Description
`--root`	`-r`	Knowledge root
`--group`		Frontmatter field to group by
`--calc`		Aggregation functions: `count`, `avg`, `sum`, `min`, `max` (with field, e.g. `avg:priority`)

kiwifs aggregate --root ./knowledge --group status --calc count --calc avg:priority

Maintenance commands

analytics — Knowledge health dashboard

Display a dashboard summarizing knowledge health, coverage, and engagement metrics (page views and failed searches).

kiwifs analytics [flags]

Flag	Short	Default	Description
`--root`	`-r`	`./knowledge`	Knowledge root
`--scope`			Path prefix to limit results
`--stale-threshold`		`30`	Days before a page counts as stale
`--format`		`text`	Output format: `text` or `json`

kiwifs analytics --root ./knowledge

lint — Validate knowledge base

Check your knowledge base for issues such as broken links, missing frontmatter, or invalid YAML.

kiwifs lint [flags]

Flag	Short	Default	Description
`--root`	`-r`		Knowledge root

kiwifs lint --root ./knowledge

janitor — Full health scan

Scan for stale pages, orphans, broken links, duplicate titles, and other hygiene issues. Exits with code 1 when error-severity issues are found.

kiwifs janitor [flags]

Flag	Short	Default	Description
`--root`	`-r`	`./knowledge`	Knowledge root
`--stale-days`		`90`	Days before a page is considered stale
`--json`		`false`	Emit JSON instead of a human summary

kiwifs janitor --root ./knowledge --stale-days 60 --json

reindex — Rebuild search indexes

Rebuild the SQLite FTS5 index from markdown files on disk. When vector search is configured, also rebuilds the vector index unless --fts-only is set.

kiwifs reindex [flags]

Flag	Short	Default	Description
`--root`	`-r`	`./knowledge`	Knowledge root
`--vector`		`false`	Force vector index rebuild (requires `[search.vector]` config)
`--fts-only`		`false`	Skip vector index even when configured

kiwifs reindex --root ./knowledge

Reindexing locks writes briefly. Run this during low-traffic periods on production servers.

view — Manage computed views

Create and regenerate computed view files (kiwi-view: true in frontmatter).

kiwifs view [subcommand] [flags]

Subcommand	Purpose
`refresh <path>`	Regenerate a view file from its `kiwi-query`
`list`	List all computed views
`create`	Create a new view file and regenerate it

Flag	Short	Default	Description
`--root`	`-r`	`./knowledge`	Knowledge root
`--query`			DQL query (`create` only, required)
`--name`			View title and filename (`create` only, required)
`--path`			Directory for the new file (`create` only)

kiwifs view list --root ./knowledge

Rules, tokens, benchmarks, clipping, and memory

rules — Manage .kiwi/rules.md

View or export the markdown rules file that steers agents across harnesses.

kiwifs rules
kiwifs rules edit
kiwifs rules export --format cursor
kiwifs rules sync --format cursor --output .cursor/rules/kiwi.md

Subcommand	Purpose
(default)	Print `rules.md` (local) or fetch from `--remote`.
`edit`	Open the file in `$EDITOR`.
`export`	Emit Cursor, Claude, AGENTS, or OpenClaw formatted snippets.
`sync`	Export and write to `--output`.

Remote operations accept --remote and --api-key like other commands.

token — API tokens in config.toml

Create scoped keys (read/write/admin) for automation or per-space access.

kiwifs token create --root ./knowledge --space docs --scope read --actor ci-reader
kiwifs token list --root ./knowledge
kiwifs token revoke kiwi_ro_abc1deadbeef

Tokens append to .kiwi/config.toml; the plaintext key is shown once on create.

bench — Local performance harness

Runs in a temporary directory with an in-process stack to benchmark writes, bulk writes, reads, and search.

kiwifs bench --files 200 --bulk 120 --search-files 5000 --search-queries 100

Outputs a markdown table suitable for issues or release notes.

clip — Save a web page as markdown

kiwifs clip https://example.com/article --root ./knowledge --folder clips/ --tags research,web

Flags: --title, --tags, --folder, --actor (defaults to clipper).

memory report — Episodic coverage

kiwifs memory report --root ./knowledge --json
kiwifs memory report --episodes-prefix agent-runs/ --json

Summarizes episodic files vs merged pages for merge pipelines (no LLM consolidation).

Flag	Default	Description
`--root`	`./knowledge`	Knowledge root
`--json`	`false`	Emit JSON instead of text
`--episodes-prefix`	from config	Override `[memory] episodes_path_prefix`

KiwiFS Cloud commands

kiwifs login
kiwifs login --host https://app.kiwifs.com

Flag	Default	Description
`--host`	`https://app.kiwifs.com`	KiwiFS Cloud host
`--client-id`	auto	WorkOS client ID (optional override)

logout — Remove stored credentials

kiwifs logout

Removes ~/.kiwifs/credentials.json.

whoami — Show authenticated user

kiwifs whoami

Prints the email and display name for the stored Cloud session.

connect — Generate MCP config for a workspace

Generate MCP server configuration for connecting an agent to a KiwiFS Cloud workspace.

kiwifs connect <workspace-slug> [flags]

Flag	Default	Description
`--key`	`$KIWI_API_KEY`	API key (optional after `kiwifs login`)
`--write`		Write config to a client: `cursor`, `claude-code`, `windsurf`, `claude-desktop`, or `auto`
`--host`	`https://api.kiwifs.com`	KiwiFS Cloud API host
`--project`	`false`	Write project-level config instead of global

kiwifs connect my-workspace --key kiwi_sk_abc123

update — Self-update the CLI

Download and install the latest kiwifs binary from GitHub Releases.

kiwifs update

Replaces the currently running binary in place.

Backup and restore

backup — Push to git remote

Push your knowledge base to a git remote for backup.

kiwifs backup [flags]

Flag	Short	Default	Description
`--root`	`-r`		Knowledge root
`--remote`			Git remote URL (overrides config)
`--branch`			Branch to push
`--rebase-before-push`		`true`	Fetch and rebase onto the backup branch before pushing

kiwifs backup --root ./knowledge --remote git@github.com:org/knowledge.git

By default, kiwifs backup fetches and rebases onto the backup branch before pushing. See Backup sync for configuration, opt-outs, and conflict handling.

restore — Clone from git remote

Clone a knowledge base from a git remote.

kiwifs restore [flags]

Flag	Default	Description
`--from`		Git remote URL (required)
`--to`		Local directory (required)
`--branch`		Branch to check out

kiwifs restore --from git@github.com:org/knowledge.git --to ./knowledge

​Core commands

​Data commands

​Maintenance commands

​Rules, tokens, benchmarks, clipping, and memory

​KiwiFS Cloud commands

​Backup and restore

Core commands

Data commands

Maintenance commands

Rules, tokens, benchmarks, clipping, and memory

KiwiFS Cloud commands

Backup and restore