> ## 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 <command> --help` for details on a specific command.

## Core commands

<AccordionGroup>
  <Accordion title="serve — Start the KiwiFS server">
    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`) |

    <CodeGroup>
      ```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
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="init — Initialize a knowledge directory">
    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` | | `kb` | Template: `kb`, `wiki`, `memory`, `tasks`, `data`, `cms`, `runbook`, `adr`, `prompt`, `research`, `log`, or `blank` |

    <CodeGroup>
      ```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
      ```
    </CodeGroup>

    <Tip>
      Templates provide a starter directory structure with sample files. Use `blank` if you want an empty knowledge base.
    </Tip>
  </Accordion>

  <Accordion title="mcp — Start MCP server">
    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`) |

    <Tabs>
      <Tab title="In-process (stdio)">
        Run KiwiFS directly within the MCP server process. Best for local development.

        ```bash theme={null}
        kiwifs mcp --root ./knowledge
        ```
      </Tab>

      <Tab title="Proxy mode">
        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
        ```
      </Tab>

      <Tab title="HTTP transport">
        Serve MCP over Streamable HTTP instead of stdio.

        ```bash theme={null}
        kiwifs mcp --root ./knowledge --http --port 8181
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="mount — FUSE mount a remote KiwiFS">
    Mount a remote KiwiFS server as a local filesystem using FUSE.

    ```bash theme={null}
    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 |

    ```bash theme={null}
    kiwifs mount ~/mnt/kiwi --remote https://kiwi.example.com --api-key my-key
    ```

    <Note>
      FUSE must be installed on your system. On macOS, install [macFUSE](https://osxfuse.github.io/). On Linux, install `fuse3`.
    </Note>
  </Accordion>
</AccordionGroup>

## Data commands

<AccordionGroup>
  <Accordion title="import — Import data from external sources">
    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` |

    <CodeGroup>
      ```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
      ```
    </CodeGroup>

    <Tip>
      Use `--dry-run` first to preview which files will be created before writing anything.
    </Tip>
  </Accordion>

  <Accordion title="export — Export knowledge base">
    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 |

    <CodeGroup>
      ```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
      ```
    </CodeGroup>

    See [Data export](/export/overview) and [Document export](/export/documents) for REST and MCP equivalents.
  </Accordion>

  <Accordion title="query — Run a DQL query">
    Run a Dataview Query Language (DQL) query against your knowledge base.

    ```bash theme={null}
    kiwifs query "<query>" [flags]
    ```

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

    ```bash theme={null}
    kiwifs query "TABLE title, status FROM 'concepts' WHERE status = 'draft'"
    ```
  </Accordion>

  <Accordion title="aggregate — SQL-style aggregation">
    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
    ```
  </Accordion>
</AccordionGroup>

## Maintenance commands

<AccordionGroup>
  <Accordion title="analytics — Knowledge health dashboard">
    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` |

    <CodeGroup>
      ```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
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="lint — Validate knowledge base">
    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
    ```
  </Accordion>

  <Accordion title="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.

    ```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
    ```
  </Accordion>

  <Accordion title="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.

    ```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 |

    <CodeGroup>
      ```bash Rebuild FTS index theme={null}
      kiwifs reindex --root ./knowledge
      ```

      ```bash Rebuild FTS and vector indexes theme={null}
      kiwifs reindex --root ./knowledge --vector
      ```
    </CodeGroup>

    <Note>
      Reindexing locks writes briefly. Run this during low-traffic periods on production servers.
    </Note>
  </Accordion>

  <Accordion title="view — Manage computed views">
    Create and regenerate computed view files (`kiwi-view: true` in frontmatter).

    ```bash theme={null}
    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) |

    <CodeGroup>
      ```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/
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Rules, tokens, benchmarks, clipping, and memory

<AccordionGroup>
  <Accordion title="rules — Manage .kiwi/rules.md">
    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.
  </Accordion>

  <Accordion title="token — API tokens in config.toml">
    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.
  </Accordion>

  <Accordion title="bench — Local performance harness">
    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.
  </Accordion>

  <Accordion title="clip — Save a web page as markdown">
    ```bash theme={null}
    kiwifs clip https://example.com/article --root ./knowledge --folder clips/ --tags research,web
    ```

    Flags: `--title`, `--tags`, `--folder`, `--actor` (defaults to `clipper`).
  </Accordion>

  <Accordion title="memory report — Episodic coverage">
    ```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` |
  </Accordion>
</AccordionGroup>

## KiwiFS Cloud commands

<AccordionGroup>
  <Accordion title="login — Authenticate with KiwiFS Cloud">
    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) |
  </Accordion>

  <Accordion title="logout — Remove stored credentials">
    ```bash theme={null}
    kiwifs logout
    ```

    Removes `~/.kiwifs/credentials.json`.
  </Accordion>

  <Accordion title="whoami — Show authenticated user">
    ```bash theme={null}
    kiwifs whoami
    ```

    Prints the email and display name for the stored Cloud session.
  </Accordion>

  <Accordion title="connect — Generate MCP config for a workspace">
    Generate MCP server configuration for connecting an agent to a KiwiFS Cloud workspace.

    ```bash theme={null}
    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 |

    <CodeGroup>
      ```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
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="update — Self-update the CLI">
    Download and install the latest `kiwifs` binary from GitHub Releases.

    ```bash theme={null}
    kiwifs update
    ```

    Replaces the currently running binary in place.
  </Accordion>

  <Accordion title="eval — Retrieval quality benchmark">
    Score FTS, semantic, and hybrid search against a golden set in `.kiwi/eval/`.

    ```bash theme={null}
    kiwifs eval --set leave-one-out --exclude-prefix drafts/ --min-hit-rate 0.6
    ```

    Topics and TREC qrels live under `.kiwi/eval/`. You can also POST the same payload to `/api/kiwi/eval`. See [Search](/concepts/search).
  </Accordion>

  <Accordion title="check — Workspace hygiene">
    Scan for sequence gaps, broken conventions, and CI-style hygiene issues.

    ```bash theme={null}
    kiwifs check --root ./knowledge
    ```

    Used by templates that rely on `<!-- seq:N -->` markers (for example `log`). Pair with `[sequences]` in config.
  </Accordion>

  <Accordion title="model download — Offline embedder">
    Download ONNX embedder artifacts for local vector search (`provider = "onnx"`).

    ```bash theme={null}
    kiwifs model download
    ```
  </Accordion>
</AccordionGroup>

## Backup and restore

<AccordionGroup>
  <Accordion title="backup — Push to git remote">
    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.
  </Accordion>

  <Accordion title="restore — Clone from git remote">
    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
    ```
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.