Knowhere CLI

A terminal client for the Knowhere document-parsing platform, built on the @ontos-ai/knowhere-sdk Node SDK.

It ships two binaries over a shared, UI-agnostic core:

| Binary | Use it for | Output | | --- | --- | --- | | knowhere | Interactive terminal UI (TUI) | Rich, animated panels | | knowhere-cli | Headless / scripting | Plain text, or JSON with --json |

Both expose the same commands and share the same authentication, so you can explore interactively with knowhere and automate with knowhere-cli.

Requirements

• Node.js >= 22

Installation

Run it directly with npx (no install, always the latest version):

npx -y @ontos-ai/knowhere-cli            # interactive TUI
npx -y @ontos-ai/knowhere-cli status <job-id>

Or install it globally to get the knowhere and knowhere-cli commands on your PATH:

pnpm add -g @ontos-ai/knowhere-cli
# or: npm install -g @ontos-ai/knowhere-cli

Both binaries come from the same package:

| Binary | Use it for | | --- | --- | | knowhere | Interactive terminal UI | | knowhere-cli | Headless / scripting |

Building from source instead? See Development.

Authentication

The CLI resolves credentials in this order:

1. --api-key flag
2. KNOWHERE_API_KEY environment variable
3. Stored OAuth credentials from knowhere login

Browser login (interactive)

knowhere login

This runs an OAuth 2.0 Authorization Code + PKCE flow: it opens your browser to the Knowhere dashboard, you approve read-only or full-access, and the resulting tokens are stored in ~/.knowhere/credentials.json (owner-only, mode 0600). The access token is refreshed automatically; knowhere logout revokes and clears it.

The Knowhere site base URL defaults to https://knowhereto.ai and can be overridden with --base-url or KNOWHERE_BASE_URL (e.g. https://staging.knowhereto.ai). The API and login routes are derived from it. For deployments where the API lives at a separate origin or path, use --api-url or KNOWHERE_API_URL to provide the exact SDK API base URL.

Browser login requires an interactive terminal, so it lives on the knowhere binary only. For headless environments, authenticate with --api-key or KNOWHERE_API_KEY.

API key (headless / CI)

export KNOWHERE_API_KEY="sk_..."
export KNOWHERE_BASE_URL="https://knowhereto.ai"   # optional; site base, /api is derived
# or, for a separate API endpoint:
export KNOWHERE_API_URL="https://api-staging.knowhereto.ai/api"

Commands

Command names use the product-facing terminal vocabulary. SDK verb names remain accepted as aliases for compatibility.

| Command | Alias | Description | | --- | --- | --- | | ingest <file\|url\|id> | parse | Upload & process a document, caching it locally | | inspect <file\|url\|id> | | Same as ingest; shows the cached result for a known doc id | | status <job-id> | | Check a parsing job's status | | download <job-id> | load | Download & unpack a finished job's result | | retrieve <text> | query | Semantic search across published documents | | get-hierarchy <doc-id> | outline | Show a cached document's section hierarchy | | read-chunks <doc-id> | | Read a cached document's chunk contents | | grep <doc-id> <pattern> | | Search one document's chunks for a literal or regex pattern | | login / logout / whoami | | Manage the session (knowhere only) |

ingest and inspect are identical: both parse the file/URL via the API, cache the result locally with a generated document id, and display it. If you pass a document id that is already cached, the result is shown without re-parsing. get-hierarchy, read-chunks, and grep accept a cached local document id, a published server doc_… id, or a completed jobId. The SDK resolves the reference: it reads configured parsed storage first, falls back to the remote document API when the snapshot is missing or stale, and schedules a bounded, non-blocking background sync into storage. When the parsed snapshot carries application-owned asset URLs, inspect, read-chunks, and retrieve preserve and display those URLs for media chunks and page-citation assets.

Parsed storage lives on disk under the cache directory (see --cache-dir / KNOWHERE_CACHE_DIR). Authenticated sessions default to an isolated ~/.knowhere/users/<scope>/cache; signed-out legacy behavior falls back to ~/.knowhere/cache. Repeated reads of the same document are served locally without re-fetching from the API.

Interactive usage (knowhere)

# Launch the interactive home (recent jobs + common commands)
knowhere

# Upload, process, and display a document
knowhere ingest ./report.pdf

# Inspect a previously parsed document by id
knowhere inspect ldoc_a1b2c3

# Search
knowhere retrieve "What are the main risks?" --top-k 5
knowhere retrieve "refund policy" --chunk-types page --namespace support-center

# Explore a cached document
knowhere get-hierarchy ldoc_a1b2c3
knowhere read-chunks ldoc_a1b2c3 --limit 20 --section "Risks / Overview"

# Search within one document (literal or --regex)
knowhere grep ldoc_a1b2c3 "revenue" --max-results 10
knowhere grep doc_b774c2247ac4 "risk|exposure" --regex

# Check or fetch a job
knowhere status job_abc123
knowhere download job_abc123 -o ./output

Animations can be disabled with --no-animation; they are also skipped automatically when output is not an interactive terminal.

Headless usage (knowhere-cli)

Plain text by default, structured JSON with --json:

knowhere-cli status job_abc123
# Job job_abc123
# Status: done
# File: report.pdf

knowhere-cli status job_abc123 --json
# { "jobId": "job_abc123", "status": "done", ... }

knowhere-cli retrieve "main risks" --top-k 3 --json | jq '.results[0]'
knowhere-cli retrieve "refund policy" --chunk-types page --json

# Search within one document; server doc ids and job ids work too
knowhere-cli grep ldoc_a1b2c3 "revenue" --max-results 10
knowhere-cli grep doc_b774c2247ac4 "risk|exposure" --regex --json

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

Options

| Option | Applies to | Description | | --- | --- | --- | | --api-key, -k | all | API key (defaults to KNOWHERE_API_KEY) | | --api-url | all | Exact Knowhere API base URL (defaults to KNOWHERE_API_URL); overrides the API URL derived from --base-url | | --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 (default: ./output) | | --query, -q | retrieve | Query text (or pass positionally) | | --top-k | retrieve | Number of results (default: 5) | | --namespace | retrieve | Retrieval namespace | | --chunk-types | retrieve | Comma-separated retrieval chunk types, for example page or page,text | | --depth | get-hierarchy | Maximum hierarchy depth to render | | --limit | read-chunks | Max chunks to read (default: 12) | | --section | read-chunks | Section-path filter | | --regex | grep | Treat the pattern as a regular expression | | --case-sensitive | grep | Match the pattern case-sensitively | | --max-results | grep | Maximum number of matches (default: 20) | | --section-prefix | grep | Restrict matches to chunks under a section-path prefix | | --cache-dir | all | Cache & parsed-storage directory (defaults to KNOWHERE_CACHE_DIR, then an auth-scoped cache) | | --no-animation | knowhere | Disable reveal animations | | --json | retrieve, get-hierarchy, grep, knowhere-cli commands | Emit machine-readable JSON |

Architecture

src/
├─ core/        UI-agnostic orchestration over the SDK (no Ink/React)
├─ screens/     Ink TUI screens — thin render layers that call core/
├─ components/  Reusable TUI widgets (panels, progress bars, badges, …)
├─ tui/         Animation context, hooks, and the Reveal helper
├─ headless/    Plain-text formatters for the headless binary
├─ auth/        OAuth (PKCE) login, credential store, token provider
├─ sdk/         Client builder + local job history
├─ theme/       Design tokens (colors, chunk palette)
├─ cli.tsx      → bin "knowhere"      (interactive TUI)
└─ headless.ts  → bin "knowhere-cli"  (headless)

The core/ layer contains all SDK orchestration and is shared verbatim by both binaries; the TUI and headless layers only differ in how they present results.

Development

Build from source:

git clone https://github.com/Ontos-AI/knowhere-cli.git
cd knowhere-cli
pnpm install
pnpm build        # bundle both binaries into dist/

Then run node dist/cli.js (or pnpm link --global to expose the commands).

Other scripts:

pnpm dev         # rebuild on change
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest