WeKnora/cli/README.md

weknora — WeKnora CLI

A command-line interface for the WeKnora RAG knowledge-base server. Lets you authenticate, manage knowledge bases and documents, run hybrid search, and ask streaming RAG questions from your terminal or from an AI agent.

$ weknora --help
WeKnora CLI lets you authenticate, browse knowledge bases, and run
hybrid searches against a WeKnora server from your shell or an AI agent.

Available Commands:
  api         Make a raw API request to the WeKnora server
  auth        Manage authentication credentials and contexts
  chat        Ask a streaming RAG question against a knowledge base
  context     Manage CLI contexts (named connection targets)
  doc         Manage documents in a knowledge base
  doctor      Run 4 self-checks: base URL, auth, server version, credential storage
  kb          Manage knowledge bases
  link        Bind the current directory to a knowledge base
  search      Search across chunks, knowledge bases, documents, or sessions
  session     Manage chat sessions
  version     Show CLI build metadata

The command surface mirrors gh CLI's <noun> <verb> convention. See AGENTS.md for the operational contract that AI agents (Claude Code, Cursor, Aider, …) can rely on: bare-JSON output shape, stderr error format, exit-code protocol, error-code registry, and per-command guidance.

---

Install

From source

Requires Go 1.24+.

git clone https://github.com/Tencent/WeKnora.git
cd WeKnora/cli
go build -o weknora .
sudo mv weknora /usr/local/bin/   # or anywhere on $PATH

Pre-built binaries

Pre-built binaries for Linux / macOS / Windows are produced by CI on each release. Grab the latest from the Releases page once v0.2 ships.

---

5-minute quickstart

# 1. Log in to your WeKnora server (interactive password prompt)
weknora auth login --host https://kb.example.com

# 2. Or pipe an API key from stdin (for CI / agents)
echo "sk-..." | weknora auth login --host https://kb.example.com --with-token

# 3. List knowledge bases
weknora kb list

# 4. Bind this directory to a knowledge base — subsequent commands auto-resolve --kb
weknora link --kb my-knowledge-base

# 5. Upload a document
weknora doc upload notes.md

# 6. Search
weknora search chunks "what is reciprocal rank fusion?"

# 7. Ask the LLM (streams to terminal)
weknora chat "summarise the design doc"

---

Multi-context

Switch between several WeKnora servers (or several tenants on the same server) without re-logging in:

weknora auth login --host https://prod.example.com    --name prod
weknora auth login --host https://staging.example.com --name staging --with-token < .staging-key
weknora auth list
weknora context use prod

Credentials are persisted to your OS keyring (Keychain on macOS, libsecret on Linux, Wincred on Windows) when available, otherwise to a 0600-mode file under $XDG_CONFIG_HOME/weknora/secrets/. The active context lives in ~/.config/weknora/config.yaml.

To remove a context's stored credentials:

weknora auth logout                  # current context
weknora auth logout --name staging   # specific
weknora auth logout --all

---

JSON output

Every command supports --json, emitting bare JSON for the resource it produces — an array for list / search, a single object for view and write outcomes:

weknora kb list --json                        # [{ "id": "kb_x", "name": "Eng" }, …]
weknora kb view kb_x --json                   # { "id": "kb_x", "name": "Eng", … }
weknora kb list --json=id,name                # project to listed fields
weknora kb list --json --jq '.[].id'          # jq over the bare data

On failure, stdout stays empty and the typed error goes to stderr in code: message\nhint: ... form:

auth.unauthenticated: fetch current user: HTTP error 401: ...
hint: run `weknora auth login`

The typed exit code (3 / 4 / 5 / 6 / 7 / 10) carries the failure class for agents that branch on it. The full error-code registry and exit-code protocol are documented in AGENTS.md.

---

Agent / scripting integration

Designed to be agent-first:

• -y/--yes skips confirmation prompts for high-risk writes. Without -y on a non-TTY/--json invocation, destructive commands return error.code: input.confirmation_required and exit code 10 so an agent can ask the user before retrying.
• --json coexists with the global --context <name> for single-shot context override.
• Set CLAUDECODE or CURSOR_AGENT environment variables to surface per-command "AI agents:" guidance in --help output.

---

Health check

Run weknora doctor for a 4-status diagnostic (OK / warn / fail / skip) covering base URL reachability, authentication, server-CLI version skew, and credential storage backend. Add --json for machine-readable output, --offline to skip network checks.

---

Development

# Run unit + contract tests
go test ./...

# Run the real-server e2e suite (requires WEKNORA_E2E_HOST + token env vars)
go test -tags acceptance_e2e ./acceptance/e2e/...

# Static analysis
go vet ./...

CI (.github/workflows/cli.yml) runs build + unit + contract tests on Linux / macOS / Windows × Go 1.24, path-filtered to changes under cli/.

---

License

MIT — see the repository LICENSE.