5.3 KiB
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/--yesskips confirmation prompts for high-risk writes. Without-yon a non-TTY/--jsoninvocation, destructive commands returnerror.code: input.confirmation_requiredand exit code 10 so an agent can ask the user before retrying.--jsoncoexists with the global--context <name>for single-shot context override.- Set
CLAUDECODEorCURSOR_AGENTenvironment variables to surface per-command "AI agents:" guidance in--helpoutput.
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.