Command Line Interface (CLI)

Use the Knowhere CLI to parse documents, inspect outlines, sync local chunk storage, and run retrieval from your terminal.

The CLI package ships two binaries over the same Knowhere SDK-backed core:

Binary	Use it for	Output
`knowhere`	Interactive terminal UI (TUI)	Rich terminal screens for local exploration
`knowhere-cli`	Headless scripting	Plain text by default, or JSON with `--json`

Both binaries use the same authentication and command vocabulary. Start in the TUI when you want to explore documents manually, and use the headless binary when you need automation in scripts or CI.

Prerequisites

Node.js 22+
A Knowhere dashboard login or a KNOWHERE_API_KEY
A terminal that supports interactive output when using the knowhere TUI

Install the CLI

Run with npx
Global install

Run the headless binary without installing it globally:

npx -y @ontos-ai/knowhere-cli --help
npx -y @ontos-ai/knowhere-cli status job_abc123 --json

To run the interactive knowhere binary through npx, select the binary explicitly:

npx -y -p @ontos-ai/knowhere-cli knowhere

Install the package globally to put both binaries on your PATH:

pnpm add -g @ontos-ai/knowhere-cli

Or with npm:

npm install -g @ontos-ai/knowhere-cli

Then run either binary:

knowhere
knowhere-cli --help

Authenticate

The CLI resolves credentials in this order:

--api-key
KNOWHERE_API_KEY
Stored dashboard login from knowhere login

Browser login
API key

Use browser login for local interactive work:

knowhere login

The login flow opens the Knowhere dashboard, asks for read-only or full-access permission, and stores credentials at ~/.knowhere/credentials.json. The CLI refreshes the access token automatically. Use knowhere logout to revoke and clear the local session.

Set KNOWHERE_BASE_URL or pass --base-url when working against a non-default environment:

KNOWHERE_BASE_URL="https://staging.knowhereto.ai" knowhere login

Browser login requires the interactive knowhere binary. For headless environments, use an API key.

Use an API key for scripts, CI, and headless environments:

export KNOWHERE_API_KEY="sk_..."
export KNOWHERE_BASE_URL="https://knowhereto.ai"

You can also pass the key per command:

knowhere-cli status job_abc123 --api-key "sk_..."

Do not commit API keys to shell scripts or shared CI logs. Prefer secret stores or environment variables.

Commands

Command names use the product-facing terminal vocabulary. The older SDK-style aliases remain accepted for compatibility.

Command	Alias	Description
`ingest FILE_OR_URL_OR_ID`	`parse`	Upload and process a document, then cache the result locally.
`inspect FILE_OR_URL_OR_ID`		Explore the parsed outline tree for a file, URL, local document ID, or Knowhere `doc_*` ID.
`sync DOC_ID_OR_JOB_ID`		Refresh local chunk storage for a parsed result.
`status JOB_ID`		Check a parsing job's status.
`download JOB_ID`	`load`	Download and unpack a finished job result.
`retrieve TEXT`	`query`	Run semantic search across published documents.
`login` / `logout` / `whoami`		Manage the local session. `login` and `logout` are available on the interactive `knowhere` binary.

ingest parses files or URLs through the Knowhere API in the shared default namespace, tags the published document metadata as CLI-created, and caches the result locally. Published Knowhere documents from default are localized into the same local cache before home, inspect, sync, and retrieve use them.

Interactive usage

Launch the terminal UI:

knowhere

Common TUI commands:

knowhere login
knowhere ingest ./report.pdf
knowhere inspect ldoc_a1b2c3
knowhere sync ldoc_a1b2c3
knowhere retrieve "What are the main risks?" --top-k 5
knowhere status job_abc123
knowhere download job_abc123 -o ./output

Use --no-animation to disable reveal animations. Animations are skipped automatically when output is not an interactive terminal.

Headless usage

Use knowhere-cli when a script needs stable stdout and exit codes:

knowhere-cli status job_abc123
knowhere-cli status job_abc123 --json
knowhere-cli retrieve "main risks" --top-k 3 --json

Errors are written to stderr and exit with a non-zero code, so the headless binary composes cleanly in shell scripts and pipelines.

Inspect and sync documents

inspect accepts:

a local file path
a remote URL
a local document ID such as ldoc_a1b2c3
a published Knowhere document ID such as doc_abc123

By default, inspect refreshes local chunk/result storage before rendering. Use --no-sync when you want to inspect the current local copy without refreshing it:

knowhere inspect doc_abc123 --no-sync
knowhere-cli inspect doc_abc123 --depth 3 --json

Use sync when you want to refresh storage explicitly:

knowhere sync doc_abc123
knowhere-cli sync job_abc123 --json

When the cached result has a server document ID, the inspect screen includes a Notebook chunk-tree link.

Options

Option	Applies to	Description
`--api-key`, `-k`	all	API key. Defaults to `KNOWHERE_API_KEY`.
`--base-url`, `-b`	all	Knowhere site base URL. Defaults to `KNOWHERE_BASE_URL`, then `https://knowhereto.ai`; API and login routes are derived from it.
`--output`, `-o`	`download`	Output directory. Defaults to `./output`.
`--query`, `-q`	`retrieve`	Query text. You can also pass the text positionally.
`--top-k`	`retrieve`	Number of retrieval results. Defaults to `5`.
`--namespace`	`retrieve`	Retrieval namespace.
`--depth`	`inspect`	Maximum outline depth to render.
`--sync` / `--no-sync`	`inspect`	Enable or disable local chunk/result refresh before inspect. Default is on.
`--no-animation`	`knowhere`	Disable reveal animations.
`--json`	`inspect`, `retrieve`, `knowhere-cli` commands	Emit machine-readable JSON.

Prerequisites​

Install the CLI​

Authenticate​

Commands​

Interactive usage​

Headless usage​

Inspect and sync documents​

Options​

See also​