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 option | Meaning |
|---|---|
[QUERY] | English query, up to 1024 bytes. Required unless --warm or --reset is given. |
--warm | Build or refresh the encoder vector cache without ranking. |
--reset | Delete the vector cache and rebuild it; ranks too when a QUERY is given. |
--full | Print 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.