v0.2.0

v0.2.0 — 2026-09-11

The release that makes grimoire-cli cover the library rather than just its
catalogue: five new command groups, a generated API client, and a rebuilt
output contract. It targets Grimoire 1.6.2 alone, and carries three breaking
changes to the CLI's own surface — 0.x, so they arrive in a minor bump.

Highlights

• The library is reachable now, not just the systems and books in it.
  search, tags, duplicates, files and backups join the vocabulary
  reads, taking the CLI from 20-odd commands to 75 covered endpoints. The
  point is what an agent can now finish without leaving the tool: find a
  duplicate, compare the copies, file one under the other as a variant, and
  delete the loser's file — or upload a book, watch it index, and fix where it
  landed.
• Breaking: --token and GRIMOIRE_TOKEN are gone. The access token now
  comes from the config file alone. Grimoire 1.6.0 cut the token's life from 30
  days to 30 minutes, which turns a pasted token from a convenience into a
  thing that expires mid-script; the CLI renews its own session from a stored
  refresh token instead, transparently and before the request rather than after
  a 401.
• Breaking: stdout is the server's bytes, unmodified. The hand-written
  response DTOs are deleted. They had to be taught every field the server
  might return, so a field Grimoire added was a field the CLI silently
  dropped — the exact failure a thin pass-through exists to avoid. Output is
  now whatever the API sent, and --pretty is the only thing that reshapes it.
• The API client is generated from Grimoire's OpenAPI spec, not
  transcribed. Kiota reads the spec straight from the pinned container, so
  the request surface cannot drift from the server it was built against, and a
  version bump produces a reviewable diff instead of a reading exercise. The
  generated models are also what validates a request body, so there is no
  hand-maintained mirror of the API's fields left to go stale.
• Grimoire 1.6.2 only, up from 1.5.6. The 1.6.x line made the library
  writable — which is why the files commands exist at all — and 1.6.2 added
  model as a fifth collection, which the resource-type flags now offer.
  Whoever stays on 1.5.6 stays on 0.1.x, maintained on
  support/grimoire-1.5.6.
• Every command's --help is written for the agent reading it. Closed
  value sets, destructive side effects, and the server quirks a thin
  pass-through leaks are documented at the call site — folder-derived fields
  that ignore a PATCH, children hidden before filters apply, which statuses map
  to exit 3. --help-full adds the request and response shapes, generated from
  the spec.

Changes

Features

• feat: accept the model collection wherever a resource type is named
• feat: add --pretty and a raw-JSON guard and field reader
• feat: add a range-constrained int option helper
• feat: add backups list, create, delete and download
• feat: add backups settings get and set
• feat: add binary output and books thumbnail
• feat: add files browse and upload
• feat: add files move, rename and delete
• feat: add search and search fields commands
• feat: add systems book-folders list and set
• feat: add systems book-folders list, set and delete
• feat: add systems cover get, upload and delete
• feat: add tags list and tags items commands
• feat: add the backups service
• feat: add the duplicate detection and dismissal commands
• feat: add the duplicate resolution commands
• feat: add the duplicates service
• feat: add the files folder subgroup
• feat: add the files service
• feat: add the vocabulary read service
• feat: add vocabulary list commands
• feat: capture the refresh cookie at login
• feat: cut systems book-folders commands before merge
• feat: generate the api client from the edge spec
• feat: refresh the access token proactively and on expiry
• feat: store the refresh token beside the access token

Fixes

• fix: accept --debug and --log-json after the subcommand
• fix: address discovery branch review findings
• fix: correct duplicates help text and close two guard holes
• fix: correct lookup command help text and test claims
• fix: generate repeated-key query params for array parameters
• fix: guard filesystem access and correct binary-io docs
• fix: harden files smoke block cleanup and error reporting
• fix: keep --pretty output UTF-8 safe end to end
• fix: keep untyped-node coverage honest and restore SavedFile drift check
• fix: let folder markers clear a container kind, tighten help/tests
• fix: point batch-tag response shape at BulkTagResult
• fix: read route roles from the container serving the spec
• fix: report rather than crash on a non-numeric range value
• fix: report the refresh token in config get, masked
• fix: scope DebugHttpHandlerTests memory target to its own logger
• fix: treat a version with no number as unknown, not ancient

Refactors

• refactor: delete the hand-written response dtos
• refactor: drop --token and GRIMOIRE_TOKEN
• refactor: drop the redundant files folder delete command
• refactor: give each vocabulary its own command file
• refactor: give each vocabulary its own service
• refactor: make each vocabulary command file self-contained
• refactor: move consumer caveats off the vocabulary commands
• refactor: pass library, addons, metadata and me responses through
• refactor: pass systems, cover and books responses through
• refactor: source help samples from the generated models
• refactor: trim the vocabulary help to its real caveats

Tests

• test: aim self-test at the raw json path
• test: avoid xUnit2031 warning in settings subgroup test
• test: correct the excluded-command count in the smoke comment
• test: cover a retired refresh token end to end
• test: cover all seven settings flags and range ceilings
• test: cover dismiss/undismiss/merge-metadata in smoke test
• test: cover system covers, book folders and binary output
• test: cover the book-folders round trip end to end
• test: cover the discovery commands in the smoke test
• test: cover the duplicates commands in the smoke test
• test: fix leaked temp files and thin test coverage from prior tasks
• test: give the fixture a book below a category directory
• test: pin the delete-folder wrapper and the upload path
• test: serialize console-mutating tests to fix parallel flake
• test: smoke-test the backup commands
• test: smoke-test the file management commands
• test: smoke-test the vocabulary read commands

Chores

• chore: bump the pinned Grimoire to 1.6.2
• chore: bump version to 0.2.0
• chore: drop obsolete generated types from json examples
• chore: ignore python bytecode from the tools scripts
• chore: pin to Grimoire 1.6.1 and regenerate the client
• chore: pin to the released Grimoire 1.6.0
• chore: remount the dev library read-write
• ci: drop the edge compose override
• ci: pin the dev stack to an edge digest and retire the epic
• ci: pin the dev stack to the nightly digest
• ci: ride the nightly tag unpinned until 1.6.0
• ci: run the edge image as a second local stack

Docs

• docs: add agent use cases to the readme
• docs: add the 1.6.0 migration reference
• docs: add the untyped-node placeholder step the plan dropped
• docs: assess grimoire 1.6.0 compatibility
• docs: collapse the repeated shape registrations in the plan
• docs: correct lookup-vocabulary consumer claim in cli-design
• docs: correct stale claims about tests and spec coverage
• docs: correct the BodyInputException namespace in the plan
• docs: correct the InlineData array wrapping in the plan
• docs: correct the book-folders read role in the spec
• docs: correct the duplicates enum and wrapper handling
• docs: correct the plan's aot claim about serializing a JsonElement
• docs: correct the untyped-array counts to the raw spec
• docs: correct the version strategy to one server per cli version
• docs: correct which bulk test file covers what
• docs: cut help text that restates flags and response fields
• docs: design covers, book folders and binary output
• docs: design the backup commands
• docs: design the discovery block
• docs: design the duplicates block
• docs: design the edge client and byte-passthrough output
• docs: design the file management commands
• docs: design the return of systems book-folders
• docs: design the vocabulary read commands
• docs: design transparent token refresh for 1.6.0
• docs: document the released install paths in the readme
• docs: document the search query syntax in help
• docs: drop the 1.5.6 fallback notes and the absent-flag bullet
• docs: drop the shipped ingest roadmap item
• docs: drop the shipped safety roadmap item
• docs: drop the shipped vocabularies roadmap item
• docs: drop the stub step from the duplicates plan
• docs: explain the 0.0.0 edge case in IsComparableVersion
• docs: fix a case-sensitive assertion in the plan
• docs: fix roadmap heading and search notes house style
• docs: fold task 1's review minors into the verification task
• docs: fold the single json-example generator into the assessment
• docs: gate the cleanup sweep on approval too
• docs: gate this branch on edge, not on 1.5.6
• docs: generalize the moving-channel comment in the dev pin
• docs: hand task 5's leftovers to the self-test task
• docs: list the searchable fields in search help
• docs: make the json guard's verdict testable in the plan
• docs: make the link kind vocabulary readable
• docs: name the real writability gate, not its backstop
• docs: pin the source clone to the build the stack runs
• docs: plan the book-folders implementation
• docs: plan the byte-passthrough work
• docs: plan the discovery implementation
• docs: plan the duplicates implementation
• docs: plan the switch to the nightly channel
• docs: point the update commands at the vocabularies
• docs: put the purge fact where it is actually true
• docs: re-measure the 1.6.0 migration against edge and sequence the work
• docs: record 1.6.0 session renewal
• docs: record book folders as measured against the 1.6.0 rc
• docs: record covers, book folders and the binary convention
• docs: record the backup commands and their server behaviour
• docs: record the byte-passthrough output contract
• docs: record the discovery commands and their verified behaviour
• docs: record the duplicates commands and their verified behaviour
• docs: record the file commands and their server behaviour
• docs: record the kiota response-model trial results
• docs: record the vocabulary commands in the README and coverage
• docs: regenerate coverage and correct the search note for 1.6.1
• docs: remove orphaned duplicate-handling reference from roadmap
• docs: replace the upload deviation this branch made stale
• docs: say deletes the files, not unlinks
• docs: say plainly what browse's record_id means
• docs: scope the books pipeline roadmap
• docs: show the approval gate before metadata is applied
• docs: specify the flag descriptions the plan had left blank
• docs: surface 1.6.2's changed scan, scaffold and unindex behaviour
• docs: sync the spec with the corrected help caveat
• docs: use real book and folder names in examples