# Changelog — `weknora` CLI All notable changes to the `weknora` CLI (the binary under `cli/` in this repository) will be documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and the CLI follows [Semantic Versioning](https://semver.org/) independently of the WeKnora server / frontend release cadence. CLI history before v0.3 is recorded in the project root [CHANGELOG.md](../CHANGELOG.md) under the release that introduced the CLI. ## [Unreleased] ### v0.5 — agent CRUD, chunk subtree, MCP chunk_list, audit-driven cleanup #### Added - `weknora agent create --model ` / `agent edit ` / `agent delete ` — hybrid surface (hot-path flags for the common fields + `--config-file` YAML/JSON for the long tail + `--generate-skeleton` template emit). `--from ` copies from an existing agent. - `weknora chunk list --doc ` / `chunk view ` / `chunk delete --doc ` — new subtree for RAG retrieval debug. Paginated with v0.4 `--limit` / `--page-size` / `--all-pages` canon. - `weknora mcp serve` adds `chunk_list` as the 10th curated tool. - `weknora agent view ` human output now renders all 34 AgentConfig fields (previously 7), grouped into 10 presentation sections. - `--all-pages` / `--page-size` on `search docs` and `search sessions` (catching up with `session list` / `doc list` canon from v0.3+v0.4). - `weknora doc list` gains `--keyword` / `--file-type` / `--source` / `--tag-id` / `--start-time` / `--end-time` (RFC3339) — matches the SDK's `KnowledgeListFilter` surface. Time flags reject malformed input with `input.invalid_argument`. - MCP `doc_list` tool gains the same 6 filter fields (`keyword`, `file_type`, `source`, `tag_id`, `start_time`, `end_time`) so agents have parity with the CLI. - `weknora session view --full` (with `--limit`, default 50, bounds 1..1000) loads chat history via `LoadMessages` and renders messages inline after session metadata. JSON mode projects messages into a `messages` array. `--limit` without `--full` errors with `input.invalid_argument`. - `weknora kb view` human render now includes `TYPE`, `PINNED` (badge, only when set), `TEMPORARY` (badge), `PROCESSING` (with doc count, only when active), `SUMMARY MODEL`, and `CREATED`. Nested config structs stay JSON-only. - `weknora doc view` human render expands to include `TITLE` (when distinct from filename), `DESC`, `SOURCE`, `CHANNEL`, `TAG`, `STORAGE` (human-readable bytes), `SUMMARY`, `ENABLED`, and `HASH` (12-char prefix). All omit-empty. - `weknora doc upload` gains `--enable-multimodel` (tri-state: unset/true/false), repeatable `--metadata key=value`, and `--channel` flags. `--enable-multimodel` and `--channel` apply to file / `--recursive` / `--from-url`; `--metadata` is file / `--recursive` only (the URL-ingest request carries no metadata field server-side, so passing it with `--from-url` is rejected up-front as `input.invalid_argument`). URL mode additionally accepts `--title`, `--file-type`, and `--tag-id`. Threads through to the SDK's `CreateKnowledgeFromFile` / `CreateKnowledgeFromURL` signatures (previously hardcoded to nil/"api" and dropped URL extras). #### Fixed - MCP `search_chunks` tool: `limit` arg now correctly threads into `SearchParams.MatchCount`. Previously the server's default cap won, silently capping below the requested limit. - `search sessions` human time format: now renders a relative duration ("2 hours ago") matching `session list`, instead of raw RFC3339. - `doc upload` (file path): re-uploading a file already ingested into the KB now surfaces as `resource.already_exists` (exit 1) instead of the misleading `network.error` ("check base URL reachability"). The SDK returns its `ErrDuplicateFile` sentinel with no `HTTP error :` prefix because the duplicate is detected via file-hash short-circuit, not by HTTP status; the previous fall-through to `WrapHTTP` therefore misclassified it. The `--from-url` branch already handled the symmetric `ErrDuplicateURL` correctly. #### Breaking changes - `weknora search docs` now applies the keyword filter server-side via `ListKnowledgeWithFilter` (was: page through every doc and substring-match client-side). Smaller wire payload on large KBs. **The match is now case-sensitive** (server uses `LIKE %keyword%`), whereas the previous client-side path lowered both sides. Callers that relied on case-insensitive matching (e.g. `search docs Q3` finding `q3 retro`) must lower-case the query themselves, or fall back to `weknora api` with a custom filter. #### Changed - `cli/AGENTS.md` MCP curation rationale rewritten: curated read-only is a deliberate product call gated on the absence of server-side per-token scope. When server-side scope ships, mutation tools can land in the MCP surface. - `cli/AGENTS.md` adds "Command surface design SOP" and "CRUD command flag canon" sections for future contributors. The design-SOP section includes a step reminding contributors to decide flag-vs-escape-hatch per field rather than trying to flag-mirror every SDK capability. - `cli/README.md` now documents the `weknora api` raw HTTP passthrough as the canonical escape hatch for deep KB config, per-request `chat` / `agent invoke` overrides, and operations without a CLI verb. ### v0.4 — output contract hardening and mainstream alignment #### Breaking changes - Dropped the JSON envelope. `stdout` now emits bare typed data (`{...}` or `[...]`); errors are written to `stderr` as `code: msg` with an actionable `hint:` line. Pipelines using `--json | jq` no longer have to filter out an envelope wrapper. - Dropped `--dry-run`. Destructive writes still require `-y/--yes`; non-TTY callers that omit `-y` exit with code 10 and `input.confirmation_required` so an agent must surface the prompt to a human before retrying. - Dropped the per-command AI footer that rendered when AI-coding-agent env detection fired. The same machine-readable guidance now lives in the standard `--help` (visible to all callers) and in `mcp serve`'s tool descriptions. #### Added - `weknora mcp serve` — curated read-only stdio MCP server exposing 9 tools (`kb_list`, `kb_view`, `doc_list`, `doc_view`, `doc_download`, `search_chunks`, `chat`, `agent_list`, `agent_invoke`). Destructive verbs are intentionally excluded. - `weknora agent list` / `agent view` / `agent invoke` — manage and call WeKnora's server-side Custom Agent resources. - `weknora auth token` — print the active credential to `stdout` for scripting (raw secret by default; `--json` emits `{token, mode, context}`). - `weknora doc upload --from-url` — ingest a remote URL. - `--json=fields,...` field projection and `--jq ` filtering on every command that emits JSON. - `--limit` and `--all-pages` on list / search commands for bounded output and explicit pagination control. - Per-resource filter flags: `kb list --pinned`, `doc list --status`, `session list --since`. #### Changed - Go toolchain bumped from 1.24 to 1.26. - `auth login --with-token` validates the supplied key against `/auth/me` before persisting, and prints an advisory if the keyring is unavailable and credentials fall back to a 0600 file under `$XDG_CONFIG_HOME/weknora/secrets/`. - AGENTS.md rewritten as a developer guide (~170 lines, 6 H2 sections). ### v0.3 — extended management surface and a `session` subtree #### Added - `context add` / `context list` / `context remove` — first-class CRUD over connection targets (previously implicit via `auth login --name`). Removing the *current* context requires explicit `-y` (exit-10 protocol) because subsequent commands have no default target. - `auth refresh` — exchanges the stored refresh token for a new access + refresh pair (OAuth refresh-token grant). Transparent 401 → refresh → retry is also wired into the SDK transport with singleflight de-dup, so most callers never need to invoke this explicitly. - `kb edit` — partial-update edit with only-sent-fields semantics (`*string` options so unset fields stay unset in the PUT body). - `kb pin` / `kb unpin` — idempotent pin/unpin toggle; no-op when already in the target state (emits `_meta.warnings`, no server call). - `kb empty` — bulk-delete documents while preserving the KB record and its config. High-risk-write; exit-10 confirmation in non-TTY / `--json` paths. - `doc view ` — show one document's metadata (title, file name, type, size, parse status, embedding model, processed-at, error message). Counterpart to `kb view` and `session view`. - `doc download` — stream a knowledge file to disk (`-O FILE` / `-O -` for stdout) with `--clobber` controlling overwrite. Rejects server-supplied path-like filenames; partial writes on error are cleaned up. - `doc upload --recursive --glob '*.md'` — walk a directory and upload every match. Per-file `OK` / `FAIL` progress lines on the human path; aggregated `uploaded[]` / `failed[]` envelope on `--json`. Exit code typed to the first failure's class on partial failure. - `search chunks` / `search kb` / `search docs` / `search sessions` — verb-noun subtree (gh `search code/repos/issues/…` shape). `search chunks` is hybrid (vector + keyword) retrieval; the other three are client-side substring filters useful for discovering identifiers. All four take `--limit N` / `-L N` (1..1000) to cap returned rows. - `session list` / `session view` / `session delete` — chat session management. - `api --input FILE` / `api --input -` — body source for raw HTTP passthrough (file or stdin); mutually exclusive with `--data`. - `unlink` — remove the cwd's `.weknora/project.yaml` so subsequent commands stop auto-resolving `--kb` from it. Walks up from cwd so a user in a subdirectory can unlink without cd-ing to the project root. - Completion smoke test guards against cobra bumps silently breaking bash / zsh / fish / powershell completion. #### SDK additions (Go client at `client/`, strictly additive) - `OpenKnowledgeFile(ctx, id) (filename, body io.ReadCloser, err)` — new primitive returning the body as a stream plus the server-suggested Content-Disposition filename. `DownloadKnowledgeFile` is now a thin wrapper (signature unchanged, gained partial-file-on-error cleanup). - `WithTransport(http.RoundTripper) ClientOption` — lets the CLI install the 401-retry transport. - `PathAuthLogin` / `PathAuthRefresh` constants — so HTTP middleware doesn't re-hardcode the literals. - `IsPinned bool` field on `KnowledgeBase` (server already returned it; SDK just hadn't modeled it).