Documentation

CLI reference / Navigate

cumaru context

Rank local files against an English query and print path:range rows with scores.

Synopsis

cumaru context [--warm] [--reset] [--full] [--scope <scope>] [QUERY]

Arguments and options

Argument or optionMeaning
[QUERY]English query, up to 1024 bytes. Required unless --warm or --reset is given.
--warmBuild or refresh the encoder vector cache without ranking.
--resetDelete the vector cache and rebuild it; ranks too when a QUERY is given.
--fullPrint every ranked file instead of the best 16.
--scope <scope>Restrict to framework, adopter, or source. Default: all three.

Side effects

  • Writes: Only the vector cache under .cumaru/.cache/context/ and, on first write, a .gitignore entry for .cumaru/.cache/. Knowledge files never change.
  • Network: None. It never downloads a model; use cumaru model pull.

Behavior

  • Scopes come from meta.context in config.yaml. Without it, every visible .cumaru/ Markdown file is ranked as adopter.
  • With an enabled bge-micro-v2 package the encoder runs on CPU; otherwise a lightweight lexical scorer runs. The backend is reported on stderr.
  • Scores run from 0.00 to 10.00. They are uncalibrated: compare ordering, not absolute values.
  • A damaged enabled model package fails explicitly. It never falls back silently.
  • A missing meta.context path is skipped silently and does not change the exit status. cumaru doctor reports it.
  • Source rows start with ./ and are relative to the project root. get reads only .cumaru/ Markdown, so read a source range with sed -n START,ENDp PATH.
  • Every range is trimmed of blank edge lines.
  • Known defect: without an enabled encoder, --reset prints the nothing-to-cache notice, exits 0, and leaves the cache on disk (upstream issue 169).

Example

cumaru context "session lifecycle"

Failures

  • Exit 1: validation, runtime, or partial-result failure. Safe rows still print.
  • Exit 2: malformed invocation, including a missing QUERY.

Sources: docs/context.md; cumaru context --help of CLI 0.15.3.

Back to all commands