Kensa

Reference

The kensa CLI

Updated for v0.16.0Edit on GitHub

kensa is a standalone command-line tool for querying, editing, and maintaining a .tms/ project from the terminal. It ships with the desktop app as a sidecar (automatically on the embedded terminal's PATH) and can also be installed on its own. It's designed to be driven both by humans and by AI agents.

It's a from-scratch Rust port of the same data model the GUI uses, with a byte-for-byte parity guarantee: editing a case with the CLI produces exactly the bytes the GUI would, so diffs stay clean.

Thirty commands across seven categories.

Read-only / query

CommandWhat it does
listList cases, or the suite tree with --tree.
show <id>Print a full case, a single --field, or --raw source.
filter <expr>Select cases with the Kensa Filter DSL (see below).
find <text>Fuzzy match on title and tags.
statsAggregate counts and averages by priority / status / tag.
index(Re)build deterministic INDEX.md + per-suite _index.md.
validateValidate cases against the schema (exit 3 on violation).
describeEmit a machine-readable manifest of the whole CLI surface.

Case creation

CommandWhat it does
newCreate a case (numeric or prefixed id), schema-aware, parity with the GUI.

Write operations

CommandWhat it does
update <id>Mutate one case: --set field=val, --add-tag, --remove-tag.
bulk …Filter + update / add-tag / remove-tag / move / delete.
rename-tag <old> <new>Rename a tag across the whole project.

Safety matrix: a single update writes immediately; all bulk operations and rename-tag are dry-run by default and require --yes to apply. bulk delete requires --to-trash (hard delete is forbidden). Writes are atomic (backup-swap) and leave timestamps untouched for GUI parity.

Quality & maintenance

CommandWhat it does
lintBuilt-in rules: imperative titles, expected-in-step, max-steps.
duplicatesJaro-Winkler title similarity, configurable --threshold.
coverageCounts --by-tag / --by-source / --by-suite.
gapsUnreferenced shared-step files.
doctorIntegrity report: dup ids, malformed frontmatter, stray files, broken refs.
changed --since <ref>Cases modified since a git ref (mtime fallback).
stale [--days N]Cases untouched for N days.
trash list|restore|purgeManage the trash (purge is dry-run by default).

Agent integration

CommandWhat it does
shared-step list|usage|orphanInspect the shared-step library.
context <id>Minimal editing context for one case.
context bundle --filter <expr> --max-tokens NContext for a filtered set under a soft token budget.
explain <id>Human/agent-readable summary + failure-point hints.
bulk-apply <script.yaml>Declarative batch of filter + operations, atomic, dry-run by default.
schema migrateDetect a v1 schema and apply the 1→2 migration.

Polish

CommandWhat it does
completions <bash|zsh|fish|powershell>Shell completion scripts.
manGenerate a roff man page.
blame <id>git blame for a case file.
log <id>git log for a case file.

Filter DSL

A small, stable (semver-contracted) query language used by filter, bulk, and context bundle. Operators cover tag, priority, status, source, date ranges, and staleness, with and / or / not composition and duration arithmetic (7d, 30m, …).

BASH
kensa filter "tag:smoke and priority:high"
kensa filter "status:active and not tag:flaky"
kensa filter "changed:<7d or stale:>30d" --format paths

Output & exit codes

  • Formats: table (default in a TTY), json (default in a pipe), jsonl, ids, paths. NO_COLOR is honored.
  • stdout carries data only; stderr carries messages.
  • Exit codes: 0 OK · 1 general error · 2 invalid arguments · 3 validation violations · 4 schema mismatch.

Project resolution

kensa finds the project via KENSA_PROJECT_ROOT (set automatically in Kensa's terminal) or by walking up from the current directory until it finds .tms/.

For AI agents

Inside Kensa's terminal the binary is already on PATH and the project root is exported, so an agent can run, e.g.:

BASH
kensa context "$TMS_CASE_ID" --format json   # gather context
kensa filter "tag:checkout" --format ids      # find related cases
kensa lint                                     # self-check after edits

The kensa-cli skill shipped with the Kensa QA plugin documents the full surface (commands, flags, DSL, exit codes, recipes) so agents use it correctly.