> ## 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. # CLI commands > KiwiFS command-line reference. All commands use the `kiwifs` binary. Run `kiwifs --help` to list available commands, or `kiwifs --help` for details on a specific command. ## Core commands Start the KiwiFS HTTP server and serve your knowledge base. ```bash theme={null} 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`) | ```bash Basic theme={null} kiwifs serve --root ./my-docs --port 8080 ``` ```bash With auth theme={null} kiwifs serve --auth apikey --api-key my-secret-key ``` ```bash With NFS and S3 theme={null} kiwifs serve --nfs --nfs-allow 10.0.0.0/8 --s3 ``` ```bash Multi-space theme={null} kiwifs serve --space team=./team-docs --space personal=./my-notes ``` Create a new knowledge directory with an optional template. ```bash theme={null} kiwifs init [flags] ``` | Flag | Short | Default | Description | | ------------ | ----- | ------------- | ------------------------------------------------------------------------- | | `--root` | `-r` | `./knowledge` | Directory to initialize | | `--template` | | `knowledge` | Template: `knowledge`, `wiki`, `runbook`, `research`, `tasks`, or `blank` | ```bash Default template theme={null} kiwifs init ``` ```bash Wiki template in a custom directory theme={null} kiwifs init --root ./wiki --template wiki ``` ```bash Blank starting point theme={null} kiwifs init --root ./docs --template blank ``` Templates provide a starter directory structure with sample files. Use `blank` if you want an empty knowledge base. Start a Model Context Protocol server over stdio transport. Use this to connect KiwiFS to AI agents and LLM tools. ```bash theme={null} 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`) | Run KiwiFS directly within the MCP server process. Best for local development. ```bash theme={null} kiwifs mcp --root ./knowledge ``` Connect to a running KiwiFS server. Best for shared or remote setups. ```bash theme={null} kiwifs mcp --remote https://kiwi.example.com --api-key my-key ``` Serve MCP over Streamable HTTP instead of stdio. ```bash theme={null} kiwifs mcp --root ./knowledge --http --port 8181 ``` Mount a remote KiwiFS server as a local filesystem using FUSE. ```bash theme={null} kiwifs mount [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 | ```bash theme={null} kiwifs mount ~/mnt/kiwi --remote https://kiwi.example.com --api-key my-key ``` FUSE must be installed on your system. On macOS, install [macFUSE](https://osxfuse.github.io/). On Linux, install `fuse3`. ## Data commands Import data from databases, files, or third-party services into your knowledge base. ```bash theme={null} 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` | ```bash Import from PostgreSQL theme={null} kiwifs import --from postgres --dsn "postgres://user:pass@localhost/mydb" \ --table articles --id-column slug --prefix articles/ ``` ```bash Import from CSV theme={null} kiwifs import --from csv --file data.csv --id-column name --prefix people/ ``` ```bash Dry run from Notion theme={null} kiwifs import --from notion --dry-run ``` Use `--dry-run` first to preview which files will be created before writing anything. Export structured data (JSONL, CSV, Parquet) or render markdown into publication formats (PDF, HTML, slides, static site). ```bash theme={null} 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 | ```bash Export as JSONL theme={null} kiwifs export --format jsonl -o knowledge.jsonl ``` ```bash Export as Parquet theme={null} kiwifs export --format parquet --include-content -o knowledge.parquet ``` ```bash Render PDF theme={null} kiwifs export --format pdf --path docs/report.md --output report.pdf --theme paper ``` ```bash Render slide deck theme={null} kiwifs export --format slides --path talks/intro.md --output slides.html ``` See [Data export](/export/overview) and [Document export](/export/documents) for REST and MCP equivalents. Run a Dataview Query Language (DQL) query against your knowledge base. ```bash theme={null} kiwifs query "" [flags] ``` | Flag | Short | Default | Description | | -------- | ----- | ------------- | -------------- | | `--root` | `-r` | `./knowledge` | Knowledge root | ```bash theme={null} kiwifs query "TABLE title, status FROM 'concepts' WHERE status = 'draft'" ``` Run aggregation queries against frontmatter fields. ```bash theme={null} kiwifs aggregate [flags] ``` | Flag | Short | Default | 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`) | ```bash theme={null} kiwifs aggregate --root ./knowledge --group status --calc count --calc avg:priority ``` ## Maintenance commands Display a dashboard summarizing knowledge health, coverage, and engagement metrics (page views and failed searches). ```bash theme={null} 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` | ```bash Full dashboard theme={null} kiwifs analytics --root ./knowledge ``` ```bash Scope to a folder theme={null} kiwifs analytics --scope students/ --stale-threshold 14 ``` ```bash JSON for automation theme={null} kiwifs analytics --format json ``` Check your knowledge base for issues such as broken links, missing frontmatter, or invalid YAML. ```bash theme={null} kiwifs lint [flags] ``` | Flag | Short | Default | Description | | -------- | ----- | ------- | -------------- | | `--root` | `-r` | | Knowledge root | ```bash theme={null} kiwifs lint --root ./knowledge ``` Scan for stale pages, orphans, broken links, duplicate titles, and other hygiene issues. Exits with code **1** when error-severity issues are found. ```bash theme={null} 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 | ```bash theme={null} kiwifs janitor --root ./knowledge --stale-days 60 --json ``` 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. ```bash theme={null} 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 | ```bash Rebuild FTS index theme={null} kiwifs reindex --root ./knowledge ``` ```bash Rebuild FTS and vector indexes theme={null} kiwifs reindex --root ./knowledge --vector ``` Reindexing locks writes briefly. Run this during low-traffic periods on production servers. Create and regenerate computed view files (`kiwi-view: true` in frontmatter). ```bash theme={null} kiwifs view [subcommand] [flags] ``` | Subcommand | Purpose | | ---------------- | -------------------------------------------- | | `refresh ` | 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) | ```bash List views theme={null} kiwifs view list --root ./knowledge ``` ```bash Refresh one view theme={null} kiwifs view refresh dashboards/active-students.md ``` ```bash Create a new view theme={null} kiwifs view create --query 'TABLE name, status FROM "students/" WHERE status = "active"' --name "Active Students" --path reports/ ``` ## Rules, tokens, benchmarks, clipping, and memory View or export the markdown rules file that steers agents across harnesses. ```bash theme={null} 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. Create scoped keys (read/write/admin) for automation or per-space access. ```bash theme={null} 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. Runs in a temporary directory with an in-process stack to benchmark writes, bulk writes, reads, and search. ```bash theme={null} kiwifs bench --files 200 --bulk 120 --search-files 5000 --search-queries 100 ``` Outputs a markdown table suitable for issues or release notes. ```bash theme={null} kiwifs clip https://example.com/article --root ./knowledge --folder clips/ --tags research,web ``` Flags: `--title`, `--tags`, `--folder`, `--actor` (defaults to `clipper`). ```bash theme={null} 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 Log in via OAuth device flow. Credentials are stored in `~/.kiwifs/credentials.json`. ```bash theme={null} 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) | ```bash theme={null} kiwifs logout ``` Removes `~/.kiwifs/credentials.json`. ```bash theme={null} kiwifs whoami ``` Prints the email and display name for the stored Cloud session. Generate MCP server configuration for connecting an agent to a KiwiFS Cloud workspace. ```bash theme={null} kiwifs connect [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 | ```bash Print config for any MCP client theme={null} kiwifs connect my-workspace --key kiwi_sk_abc123 ``` ```bash Auto-write to Cursor theme={null} kiwifs connect my-workspace --write cursor --project ``` Download and install the latest `kiwifs` binary from GitHub Releases. ```bash theme={null} kiwifs update ``` Replaces the currently running binary in place. ## Backup and restore Push your knowledge base to a git remote for backup. ```bash theme={null} 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 | ```bash theme={null} 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](/deploy/backup-sync) for configuration, opt-outs, and conflict handling. Clone a knowledge base from a git remote. ```bash theme={null} kiwifs restore [flags] ``` | Flag | Default | Description | | ---------- | ------- | -------------------------- | | `--from` | | Git remote URL (required) | | `--to` | | Local directory (required) | | `--branch` | | Branch to check out | ```bash theme={null} kiwifs restore --from git@github.com:org/knowledge.git --to ./knowledge ```