cc8254f862
Two intertwined mainstream-alignment moves bundled because they share
the migration target (every command's --json path):
1. Drop --dry-run entirely. Survey of comparable API-wrapper CLIs
(gh, aws, stripe, lark): none expose --dry-run. The mainstream that
does (kubectl/git/helm/ansible) operates on declarative manifests
or local state where the preview is materially different from the
executed action. WeKnora's CLI just echoed the same parameters
that would have gone on the wire — the preview added no real
signal over `--help` + reading the call site. Removes:
- root --dry-run persistent flag + cmdutil/dryrun.go
- DryRun fields + EmitDryRun calls in 12 write commands
- format.Envelope.DryRun field
- 8 corresponding *_test.go cases
- --dry-run mention from README.md and CHANGELOG.md
- "dry_run":false from 16 golden envelopes
2. Migrate every --json output to bare data:
- New format.WriteJSON / WriteJSONFiltered helpers
(cli/internal/format/bare.go) share filterArrayItems /
filterObjectKeys / writeJQ with the (still-live for now) envelope
filter helpers.
- Read commands (kb/doc/session list+view, search chunks/docs/
sessions/kb, auth list/status, agent list/view, context list,
doctor) emit bare arrays / objects on stdout.
- Write commands (kb create/edit/delete/pin/empty, doc upload/
upload_recursive/delete, session delete, auth login/logout/
refresh/token, link/unlink, context add/use/remove, agent
invoke, chat, api, version) emit bare result objects. Risk
classification dropped — the resource + exit code already
convey the action.
Per-command shape changes:
list / search → []T (was {ok, data:{items:[…]}})
view → T (was {ok, data:T, _meta:…})
create / edit → T
delete / pin / etc. → {id, …action result…}
doctor → {summary, checks}
api → {status, headers, body}
_meta dropped on the read path:
pagination (page/page_size/total/has_more) — agents iterate with
--all-pages or accept --limit (gh CLI parity);
kb_id / context echo — caller already knows what it asked for.
Acceptance contract goldens regenerated for the new bare shape.
Error envelope on stdout (PrintErrorEnvelope) stays live for now —
the envelope-infra deletion lands in the next commit.
183 lines
4.9 KiB
Markdown
183 lines
4.9 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
$ 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](AGENTS.md) for the operational contract that AI agents
|
||
(Claude Code, Cursor, Aider, …) can rely on: envelope schema, exit-code
|
||
protocol, error-code registry, and per-command guidance.
|
||
|
||
---
|
||
|
||
## Install
|
||
|
||
### From source
|
||
|
||
Requires Go 1.24+.
|
||
|
||
```bash
|
||
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](https://github.com/Tencent/WeKnora/releases)
|
||
once v0.2 ships.
|
||
|
||
---
|
||
|
||
## 5-minute quickstart
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
weknora auth logout # current context
|
||
weknora auth logout --name staging # specific
|
||
weknora auth logout --all
|
||
```
|
||
|
||
---
|
||
|
||
## JSON envelope output
|
||
|
||
Every command supports `--json`, returning a stable envelope shape:
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": { /* command-specific payload */ },
|
||
"_meta": { "context": "prod", "kb_id": "a32a63ff-fb36-4874-bcaa-30f48570a694" }
|
||
}
|
||
```
|
||
|
||
On error:
|
||
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": {
|
||
"code": "auth.unauthenticated",
|
||
"message": "...",
|
||
"hint": "run `weknora auth login`"
|
||
}
|
||
}
|
||
```
|
||
|
||
The full schema, error-code registry, and exit-code protocol (0 / 1 / 2 / 10
|
||
/ 130) are documented in [AGENTS.md](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
|
||
|
||
```bash
|
||
# 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](../LICENSE).
|