CLI commands

Every kiwifs command and subcommand, with flags and defaults.

Everything ships in one kiwifs binary. Run kiwifs --help to list commands, kiwifs <command> --help for details, and kiwifs --version to print the version.

Most commands that work on a knowledge base take --root (-r), which defaults to ./knowledge.

Group	Commands
Server and agents	serve, init, mcp, mount, lsp
Restructuring	refactor plan, refactor apply, refactor revert
Data	import, export, query, aggregate, view
Quality and maintenance	check, lint, janitor, analytics, eval, reindex, widgets
Agent setup	rules, token, memory report, clip, model download
Backup and tooling	backup, restore, bench, update
KiwiFS Cloud	login, logout, whoami, connect

Server and agents

serve

Start the HTTP server: REST API, web UI, and Streamable HTTP MCP at /mcp. Optional protocol servers (NFS, S3, WebDAV) run alongside.

Basic

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

Core flags

Flag	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 with --auth apikey)
--oidc-issuer		OIDC issuer URL (required with --auth oidc)
--oidc-client-id		OIDC client ID (required with --auth oidc)
--async-commit	true	Batch git commits asynchronously
--batch-window	200	Async commit batch window, in milliseconds
--batch-max-size	50	Max paths per async commit batch
--no-watch	false	Disable the watcher that picks up direct writes to --root
--space		Register an additional space, name=path (repeatable). Enables routing at /api/kiwi/{name}/...

Protocol flags

Flag	Default	Description
--nfs	false	Enable the userspace NFSv3 server
--nfs-port	2049	NFS port
--nfs-allow	localhost only	Comma-separated CIDRs allowed to mount NFS
--s3	false	Enable the S3-compatible API
--s3-port	3334	S3 port
--webdav	false	Enable the WebDAV server
--webdav-port	3335	WebDAV port

init

Create a knowledge directory from a template.

Terminal

kiwifs init                                  # kb template in ./knowledge
kiwifs init --root ./wiki --template wiki
kiwifs init --root ./docs --template blank

Flags

Flag	Default	Description
--root, -r	./knowledge	Directory to initialize
--template	kb	kb, wiki, data, cms, memory, runbook, adr, prompt, research, log, tasks, or blank

See Templates for what each one contains.

mcp

Start the MCP server. It opens a directory in-process (--root) or proxies to a running server (--remote), over stdio or Streamable HTTP.

In-process (stdio)

kiwifs mcp --root ~/knowledge

Flags

Flag	Default	Description
--root		Knowledge root (in-process mode)
--remote		KiwiFS server URL (proxy mode)
--api-key		API key for the remote server, sent as a bearer token
--space	default	Space to scope to (--remote only)
--http	false	Serve Streamable HTTP at /mcp instead of stdio
--port	8181	HTTP port (requires --http)

Exactly one of --root or --remote is required. kiwifs serve already exposes MCP at /mcp, so you only need kiwifs mcp --http for a standalone MCP server. See MCP for client setup and the tool list.

mount

Mount a remote KiwiFS server as a local filesystem with FUSE. Not available on Windows.

Terminal

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

Flags

Flag	Default	Description
--remote		Remote KiwiFS server URL (required)
--api-key	$KIWIFS_API_KEY	API key, sent as X-API-Key
--bearer	$KIWIFS_BEARER	Bearer token for the Authorization header
--basic-user		HTTP Basic username
--basic-pass	$KIWIFS_BASIC_PASS	HTTP Basic password
--space		A non-default space to mount

Install macFUSE on macOS or fuse3 on Linux first.

lsp

A language server on stdin and stdout. When your editor renames or moves markdown files, it answers with the link edits that keep every link pointing at them, computed by the same planner as kiwifs refactor. Point your editor’s generic LSP client at it.

Terminal

kiwifs lsp --root ./knowledge

Flags

Flag	Default	Description
--root, -r	the editor’s workspace folder	Knowledge root

Restructuring

refactor

Move, merge, split, and edit pages from a manifest without breaking links. Each apply is one commit that you can revert. See Restructuring for the manifest format.

Subcommand	Description
refactor plan MANIFEST	Preview a restructuring. Writes nothing. Exits 1 if the plan has errors.
refactor apply MANIFEST	Show the plan, confirm, and apply it as one commit.
refactor revert COMMIT	Show what reverting a commit would change, confirm, and apply it as a new commit. Refuses if affected files changed since. Requires git versioning.

Terminal

kiwifs refactor plan reorg.yaml --verbose
kiwifs refactor plan reorg.yaml --diff
kiwifs refactor apply reorg.yaml --yes
kiwifs refactor revert 3f9c2ab

If a KiwiFS server is serving --root, apply and revert send the change to that server so its index and live readers stay consistent.

Flags for plan, apply, and revert

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--json	false	Print the plan as JSON
--verbose, -v	false	List every rewritten link
--diff	false	Print a unified diff for every written page

Extra flags for apply and revert

Flag	Default	Description
--yes, -y	false	Apply without asking
--server	http://127.0.0.1:<port from config>	Server to send the change to when one holds --root
--api-key	$KIWI_API_KEY	API key for that server
--actor	cli:refactor	Actor recorded in the commit

Data

import

Import records from databases, files, or services. Each record becomes a markdown page with frontmatter.

PostgreSQL

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

Category	--from values
Databases	postgres, mysql, sqlite, mongodb, firestore, dynamodb, redis, elasticsearch
Files	markdown, csv, json, jsonl, yaml, excel, bibtex, croissant
Services	notion, airtable, gsheets, obsidian, confluence

Common flags

Flag	Default	Description
--from		Source type (required)
--root, -r	./knowledge	Knowledge root
--prefix	table or collection name	Path prefix for imported pages
--columns		Comma-separated columns to include
--id-column	auto-detect	Column used as the file name
--limit	0	Max rows (0 = unlimited)
--dry-run	false	Show what would be imported without writing
--infer-schema	false	Infer a JSON Schema from a csv, json, or jsonl sample and print it
--save-schema	false	Save the inferred schema to .kiwi/schemas/<name>.json (with --infer-schema)

Source-specific flags

Flag	Used by
--dsn	postgres, mysql connection string
--uri	mongodb connection URI
--db	sqlite database file
--file	csv, json, jsonl, yaml, excel, bibtex, croissant
--path	markdown, obsidian, confluence directory
--table	postgres, mysql, sqlite, dynamodb
--query	Custom SQL (overrides --table)
--collection	firestore, mongodb
--database	mongodb database name
--project	firestore GCP project ID
--database-id	notion database ID
--base-id, --table-id	airtable
--sheet	excel, gsheets sheet name
--spreadsheet-id, --credentials	gsheets
--region	dynamodb AWS region
--addr, --password, --redis-db (default 0), --pattern	redis
--url	elasticsearch or Confluence API server URL; croissant metadata URL
--index	elasticsearch index
--api, --space	confluence live API mode and space key

See Import for per-source setup.

export

Export structured data (JSONL, CSV, Parquet) or render markdown to PDF, HTML, slides, or a static site.

JSONL

kiwifs export --format jsonl -o knowledge.jsonl

Data flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--format	jsonl	jsonl, csv, parquet, mkdocs, pdf, html, slides, or site
--output, -o	stdout for data formats	Output file
--path		File or directory to export
--columns		Comma-separated frontmatter fields (CSV)
--include-content	false	Include the full markdown body
--include-links	false	Include outgoing and incoming links
--include-embeddings	false	Include vector embeddings
--limit	0	Max files (0 = unlimited)
--webhook		POST export metadata to this URL after a successful export
--webhook-secret	from config	HMAC signing secret for the webhook

Document flags

Flag	Default	Description
--theme		paper, modern, minimal, dark, or presentation
--self-contained	false	Embed all resources in HTML or PDF output
--bibliography		Path to a .bib or .json bibliography
--csl		Citation style: apa, ieee, chicago, vancouver, harvard
--crossref	false	Number and cross-reference figures, tables, and equations
--pdf-engine	auto-detect	typst or xelatex
--slide-format	html	html, pdf, or pptx
--site-name		Site name (MkDocs)
--site-url		Site URL (MkDocs)
--repo-url		Repository URL (MkDocs)

See Data export and Document export.

query

Run a DQL query against the index. Run kiwifs reindex first if the index is empty.

Terminal

kiwifs query 'TABLE name, status FROM "students/" WHERE status = "active"'
kiwifs query 'DISTINCT status' --format list
kiwifs query 'LIST FROM "concepts/" SORT _updated DESC' --limit 10

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--format	table	table, list, json, or count
--limit	0	Max results (overrides the query’s LIMIT)
--sort		Sort field (overrides the query’s SORT)
--order		asc or desc

aggregate

Group pages by a frontmatter field and compute aggregates.

Terminal

kiwifs aggregate --group status
kiwifs aggregate --group status --calc "count,avg:mastery,max:score" --path students/

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--group		Field to group by (required)
--calc	count	Comma-separated: count, avg:field, sum:field, min:field, max:field
--path		Path prefix to scope results
--where		DQL WHERE filter expression

view

Manage computed view pages (kiwi-view: true in frontmatter), whose body is generated from the DQL in kiwi-query.

Subcommand	Description
view list	List computed view files
view refresh <path>	Regenerate one view
view create	Create a view file and generate it

Terminal

kiwifs view list
kiwifs view refresh dashboards/active-students.md
kiwifs view create --query 'TABLE name, status FROM "students/"' --name "Active Students" --path reports/

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root (all subcommands)
--query		DQL query (create, required)
--name		View name, used as the file name (create)
--path	root	Directory for the new view (create)

Quality and maintenance

check

CI-friendly scan: janitor hygiene checks, plus sequence gaps in <!-- seq:N --> markers when [sequences] is configured. Exits 0 when clean, 1 when issues are found, 2 when the scan fails.

Terminal

kiwifs check --root ./knowledge --fail-on-warn

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--stale-days	90	Days before a page is considered stale
--json	false	Emit JSON
--fail-on-warn	false	Exit 1 on warnings, not only errors

lint

Validate a knowledge directory against its SCHEMA.md: orphans referenced by the schema, broken wiki links, empty files, and a missing schema. Exits 1 if any issues are found.

Terminal

kiwifs lint --root ./knowledge --json

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--json	false	Emit JSON

janitor

Scan for hygiene issues: stale, orphan, duplicate titles, contradictions, missing owner or status, empty pages, broken links, missing review dates, decisions in meeting notes, expired memory, and stale runbooks. Exits 1 on error-severity issues.

Terminal

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

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--stale-days	90	Days before a page is considered stale
--json	false	Emit JSON

Runbook staleness is opt-in through [janitor.execution_staleness] in .kiwi/config.toml. See Configuration.

analytics

Summarize knowledge health, coverage, and engagement (page views and failed searches).

Terminal

kiwifs analytics --scope students/ --stale-threshold 14 --format json

Flags

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

eval

Measure retrieval quality (Hit Rate, MRR, Precision@K, nDCG@K) for full-text and, when configured, vector search against a golden set in .kiwi/eval/ (<name>.qrels in TREC format and <name>.topics). Exits non-zero when a threshold is not met, so it can gate CI.

Terminal

kiwifs eval --list
kiwifs eval --set leave-one-out -x projects/atlas/ --top-k 10
kiwifs eval --set leave-one-out --format json --min-hit-rate 0.6

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--set		Golden set name under .kiwi/eval/
--list	false	List golden sets and exit
--exclude-prefix, -x		Hide a path prefix from retrieval before ranking (repeatable)
--top-k	5	Rank cutoff for every metric
--format	text	text or json
--min-hit-rate	0	Fail if the best engine’s hit rate is below this
--min-mrr	0	Fail if the best engine’s MRR is below this
--min-ndcg	0	Fail if the best engine’s nDCG is below this

See Search.

reindex

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

Terminal

kiwifs reindex --root ./knowledge
kiwifs reindex --root ./knowledge --vector

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--vector	false	Require a vector rebuild; fails if [search.vector] is not enabled
--fts-only	false	Skip the vector index even when configured

widgets

Inspect widget fences and find blocks that could use them.

Subcommand	Description
widgets list [fence]	List the widget fences, or describe one
widgets suggest [path]	Find widget:live blocks that could be typed fences. Read-only: prints drafts, rewrites nothing.

Terminal

kiwifs widgets list tree
kiwifs widgets suggest --root ~/knowledge --json

Flags

Flag	Default	Description
--json	false	Emit JSON (list, suggest)
--root, -r	./knowledge	Directory scanned when no path is given (suggest)

Agent setup

rules

View and export .kiwi/rules.md, the plain-markdown rules that steer agents across harnesses.

Subcommand	Description
rules	Print the rules (local file, or from --remote)
rules edit	Open the rules in $EDITOR
rules export	Print the rules in a harness-specific format
rules sync	Export and write to a file

Terminal

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

Flags

Flag	Default	Description
--remote		KiwiFS server URL. Reads the local .kiwi/rules.md when omitted
--api-key		API key for the remote server
--format	cursor	cursor, claude, agents, openclaw, or skill (export, sync)
--output, -o		Output file (sync, required except for --format skill, which defaults to .cursor/skills/team-wiki/SKILL.md)

token

Create, list, and revoke scoped API tokens in .kiwi/config.toml. The plaintext key is shown once on create.

Terminal

kiwifs token create --space docs --scope read --actor ci-reader
kiwifs token create --space secure --scope write --prefix docs/ --actor ci-bot
kiwifs token list
kiwifs token revoke kiwi_ro_abc1

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root (all subcommands)
--space		Space the token is scoped to (create)
--scope	read	read, write, or admin (create)
--prefix		Path prefix restriction (create)
--actor	<scope>-token	Actor recorded in audit logs (create)

token revoke <key-prefix> takes the first 12 characters of the key. See Auth tokens.

memory report

List episodic files and whether any page cites them under merged-from, for consolidation pipelines.

Terminal

kiwifs memory report --root ./knowledge --json

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--json, -j	false	Print JSON instead of a table
--episodes-prefix	[memory] episodes_path_prefix, or episodes/	Episode path prefix

clip

Fetch a web page, extract the article, and save it as markdown with frontmatter.

Terminal

kiwifs clip https://example.com/article --folder bookmarks/ --tags research,web

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--title, -t		Override the page title
--tags		Comma-separated tags
--folder, -f	clips/	Target folder
--actor	clipper	Actor recorded for the write

model download

Download ONNX embedding model and tokenizer files from Hugging Face for offline vector search. Models: all-minilm-l6-v2 (default, English, 384 dimensions) and multilingual-e5-small (multilingual and CJK, 384 dimensions).

Terminal

kiwifs model download
kiwifs model download multilingual-e5-small

Flags

Flag	Default	Description
--dir	~/.kiwi/models/<model>	Output directory

Then configure vector search with provider = "onnx" and the printed paths.

Backup and tooling

backup

Push the knowledge repo to a git remote. By default it fetches and rebases onto the backup branch first.

Terminal

kiwifs backup --root ./knowledge --remote [e-mail]:org/knowledge.git

Flags

Flag	Default	Description
--root, -r	./knowledge	Knowledge root
--remote	from config	Git remote URL
--branch	current branch	Branch to push
--rebase-before-push	true	Fetch and rebase onto the backup branch before pushing

See Backup sync.

restore

Clone a knowledge base from a git remote.

Terminal

kiwifs restore --from [e-mail]:org/knowledge.git --to ./knowledge

Flags

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

bench

Benchmark single writes, bulk writes, reads, search, and storage overhead in a temporary directory with an in-process stack. Prints a markdown table.

Terminal

kiwifs bench --files 200 --search-files 5000

Flags

Flag	Default	Description
--files	50	Files for write and read benchmarks
--bulk	100	Files for the bulk write benchmark
--search-files	1000	Files to index for the search benchmark
--search-queries	50	Search queries to run

update

Download the latest kiwifs release from GitHub and replace the running binary in place. No flags.

Terminal

kiwifs update

Other commands check for a newer version in the background, at most once every 24 hours.

KiwiFS Cloud

These commands work with hosted workspaces. See KiwiFS Cloud.

login

Sign in with the OAuth device flow: the CLI shows a code, you confirm it in your browser, and the session is stored in ~/.kiwifs/credentials.json.

Terminal

kiwifs login

Flags

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

logout

Remove the stored credentials.

Terminal

kiwifs logout

whoami

Show the signed-in user.

Terminal

kiwifs whoami

connect

Print or write MCP client config for a workspace, with your API key embedded.

Print config

kiwifs connect my-workspace --key kiwi_sk_abc123

Flags

Flag	Default	Description
--key	$KIWI_API_KEY	API key (optional after kiwifs login)
--write		Write 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 (Cursor, Claude Code)

Related

Configuration

Settings in .kiwi/config.toml that the CLI reads.

MCP

Connect agents and browse the 78 tools.

Restructuring

The manifest format behind kiwifs refactor.

REST API

HTTP equivalents for most commands.