weknora-shared

WeKnora CLI — shared base

weknora is the agent-first CLI for a WeKnora RAG server. Every command prints a JSON envelope and uses a typed exit code, so you branch on machine-readable output, not prose. Read this skill before any task-specific weknora-* skill.

1. Authenticate (do this first — order matters)

Agents usually skip profiles entirely: set WEKNORA_API_KEY (or WEKNORA_TOKEN) + WEKNORA_HOST and every command authenticates statelessly and zero-disk — no profile add / auth login needed. auth token echoes that env credential; auth status / doctor confirm it. The steps below set up a persistent named profile instead (interactive / multi-environment use).

Authentication is a two-step sequence. weknora auth login operates on the active profile, so the profile must exist first:

# 1. register a connection target and make it active
weknora profile add prod --host https://kb.example.com --use
# 2a. API key (agent default — pipe the key on stdin, non-interactive):
echo "$WEKNORA_API_KEY" | weknora auth login --with-token
# 2b. OR email+password (interactive prompt only — no flags; not for agents)
weknora auth login

weknora auth status          # verify: who am I, which tenant

• Target a non-active profile for one command with the global --profile NAME (e.g. weknora --profile staging auth refresh). There is no per-command --name/--host on auth commands.
• Get the raw token for scripting with WEKNORA_TOKEN=$(weknora auth token) (raw token by default; works with an env credential too; --format json gives the {token, mode, profile} envelope).
• weknora auth logout clears a profile's stored credentials but keeps the profile registered (re-auth later with auth login); use profile remove to delete the profile entirely.
• weknora doctor runs 4 health checks (reachability, credential, version, storage).

2. Selecting a knowledge base (--kb)

--kb accepts a name or a UUID (resolved server-side). Resolution order: --kb flag → WEKNORA_KB_ID env → directory link (weknora link --kb X binds the cwd) → error. Read/create commands that operate "inside a project" inherit the link; search * and destructive --all operations always require an explicit --kb (so an agent never silently hits the wrong corpus).

A KB must have an embedding model bound to be searchable. A freshly created KB is retrieval_ready:false — uploaded docs stay unindexed and search/chat return nothing until you bind models. Create it ready in one step (kb create --embedding-model <m> --chat-model <m>, discover ids with weknora model list) or bind after the fact (kb config set <kb> --embedding-model <m> --chat-model <m>). kb status / kb check report retrieval_ready, and kb create hints the fix when it is false — so an unconfigured KB is never silently "healthy".

3. Output contract — every command

Default output is --format json: a single envelope.

• error.type is a stable typed code (e.g. local.kb_not_found, input.invalid_argument, input.confirmation_required, server.error). Branch on it; error.hint usually tells you the next action.
• --format text = a live human-readable projection. chat and session ask buffer a bounded answer-event projection into one JSON envelope by default; pass --reference for indexed citations, --verbose for execution detail, or --format ndjson for raw event lines. session resume remains an NDJSON streaming command.
• --jq '<expr>' filters the envelope (e.g. weknora kb list --jq '.data[].id').
• Exception: weknora auth token emits the raw token by default (it's a scripting helper); pass --format json for the {token, mode, profile} envelope.
• Batch / wait caveat: multi-item commands come in two shapes, but for both you branch on the exit code, not ok:
  • doc/chunk/session delete with several ids → a batch envelope: status is success/partial/error, ok is true only when every item succeeded (ok:false on any failure), data is a per-item array [{id, ok, result|error}], and meta.successes/failures count the split. Exit 1 if any item failed.
  • doc wait → a normal ok:true envelope whose data partitions the ids into {completed, failed, timeout}; ok stays true even with failures (to avoid a contradictory envelope). Exit 1 if any doc failed, 124 on timeout. Either way, read the exit code first, then data for which items failed.

4. Exit codes (branch on these)

Note: a server resource id that doesn't exist → exit 4 (resource.not_found); a --kb name that doesn't resolve client-side → exit 1 (local.kb_not_found). input.invalid_argument spans two exit codes — a malformed invocation (unknown/missing flag, wrong arg count) exits 2 (fix the command, re-check --help), while a value rejected after parsing (e.g. a bad --jq expression) exits 5 (adjust the value, retry). Branch on the exit code to tell them apart.

5. Destructive writes (exit 10) — hard rule

Destructive commands (kb/doc/chunk/session/agent delete, kb/agent update, auth logout, doc delete --all, …) without -y exit 10 with error.type = input.confirmation_required and error.risk = {level, action}:

{"ok":false,"error":{"type":"input.confirmation_required",
  "message":"delete knowledge base X requires explicit confirmation: re-run with -y",
  "retry_argv":["weknora","kb","delete","X","-y"],"risk":{"level":"destructive","action":"kb.delete"}}}

Surface this to the user and get explicit approval. Re-run with -y ONLY after they approve. Never add -y on your own initiative.

6. Preview before acting — --dry-run

Any mutation accepts --dry-run: it resolves the request, prints meta.plan = {action, args}, makes zero server/side-effect changes, exits 0. Use it to confirm a command is well-formed (and what it would do) before running it for real — especially before destructive or bulk operations.

7. Chaining (mutation → id)

Mutations return the new resource id in data.id. Chain with it:

KB=$(weknora kb create "Docs" --jq '.data.id' --format json | tr -d '"')
weknora doc upload ./manual.pdf --kb "$KB"

7a. Reliability patterns for long-running agent runs

Inspecting prior messages

Use weknora message list --session <sess-id> to review the message history of a session (e.g., after a stream drops) before deciding whether to re-ask or continue. Use weknora message search "<query>" to locate a prior Q&A exchange across all sessions — prefer this over re-running an expensive query when the answer may already exist.

Tool-approval unlock

An agent run pauses mid-stream on a tool-approval event when the server requires human sign-off before executing a tool call. The pattern:

1. The stream emits a tool-approval event; capture the pending_id.
2. Surface the pending tool call to the user (show tool name + proposed args). Do not auto-approve.
3. After explicit user go-ahead: weknora session tool-approval resolve <pending-id> -y to approve, or add --reject --reason "..." to reject.
4. Resume the answer: weknora session resume <sess-id> --message <msg-id>.

--modified-args '{"key":"val"}' replaces the tool arguments on approve (non-empty JSON object required). This is an exit-10 interaction — see §5.

8. Resource model & command map

kb        knowledge bases   list/view/create/update/delete/pin/unpin/status/check
doc       documents in a KB list/view/create/upload/fetch/download/reparse/update/delete/wait
chunk     retrieval units   list/view/delete   (RAG debug; not search)
session   conversations     list/view/delete/ask/stop/resume/tool-approval resolve
message   session messages  list/search/delete
agent     custom agents     list/view/create/update/delete/status/check
model     configured models list/view/create/update/delete   (update rotates key / base-url in place, id preserved)
search    retrieval         chunks / docs / kb / sessions
chat      one-shot KB RAG Q&A (streaming)
api       raw HTTP passthrough to any server endpoint (escape hatch)
link/unlink  bind cwd to a KB        mcp serve  expose weknora as MCP tools

chat vs session ask vs search — the most common confusion: see the weknora-rag-search skill for the decision table. Briefly: chat = one-shot KB Q&A with an LLM; session ask --agent <id> = invoke a custom agent; search chunks = raw hybrid retrieval (no LLM).

9. CLI vs MCP

For your own scripted control, use the CLI (richer: dry-run, exit-10, all verbs). For an IDE/host agent that speaks MCP, weknora mcp serve exposes a curated read+chat tool set: kb_list, kb_view, doc_list, doc_view, doc_download, search_chunks, chunk_list, agent_list, chat, session_ask. MCP tools take raw ids (no name resolution); resolve names via kb_list first.

10. Agent self-help

Run weknora <command> --help. With WEKNORA_AGENT_HELP=1 set, --help emits a JSON blob (used_for / required_flags / examples) instead of prose — parse that to learn a command without scraping the human help table.

Common mistakes