CLI Reference¶

The kbars command-line tool ships with the cli module. It renders templates against JSON or YAML contexts and runs the conformance suite against a kBars implementation in any language.

Install¶

brew install commonsguy/kbars/kbars

Or tap first:

brew tap commonsguy/kbars
brew install kbars

Homebrew installs OpenJDK automatically if it isn't already present. This is the recommended way to get kbars on your PATH; see Build below for the from-source alternative.

If you also work inside a checkout of the kBars repo itself, a kbars invocation there resolves differently: the repo's .envrc (via direnv) prepends its own bin/ to PATH, and bin/kbars execs the locally-built cli/build/libs/kbars-all.jar — so kbars inside the checkout always runs your local build, while kbars anywhere else runs the Homebrew install. Both wrap a binary literally named kbars, which is what makes this work.

Build¶

./gradlew :cli:shadowJar

Produces cli/build/libs/kbars-all.jar. With direnv enabled, the repo-root .envrc adds bin/ to PATH, so inside the project directory kbars runs directly without the java -jar prefix.

Synopsis¶

kbars [--version] <command> [<args>]

Commands¶

kbars render¶

Renders one or more templates against zero or more contexts (cross-product): every --template renders against every --context.

kbars render [OPTIONS]

Options¶

At least one --template is required. Stdin may be used for at most one option per invocation (across --template and --context combined).

Examples¶

Render a single template with a JSON context:

kbars render -t hello.kbars -c context.json

Render from stdin with a context file:

echo "Hello {{ name }}!" | kbars render -t - -c context.json

Render two templates against two contexts (four output blocks, separated by the divider):

kbars render -t header.kbars -t body.kbars -c alice.json -c bob.json

--json envelope¶

With --json, exactly one JSON object is written to stdout, regardless of outcome. The outcome field (a class discriminator) identifies the variant:

// outcome: output — the template rendered successfully
{"outcome":"output","output":"Hello Alice!","softFails":["KB-5006"]}

// outcome: error — a KbParseException or KbRenderException was raised
{"outcome":"error","errorCode":"KB-2001","message":"..."}

// outcome: invalid-context — the context was not valid JSON or YAML, or not an object
{"outcome":"invalid-context","message":"..."}

softFails lists the stable conformance error codes (e.g. "KB-5006") of every soft-fail event reported during the render, in render order — see Soft failures and Error Codes. Exit codes are unchanged from human mode: 0 on output, 1 on error or invalid-context.

Exit codes¶

Byte fidelity¶

Human-mode stdout preserves rendered output byte-for-byte, including any \r a template's literal text contains — nothing normalizes line endings on the way out — but it appends one trailing \n after each render for readability. When a consumer needs the exact rendered bytes with no added newline, use --json's output field, which carries the render result verbatim (JSON-escaped) with nothing appended.

kbars conformance¶

Runs the render conformance suite against one or more filesystem paths.

kbars conformance [OPTIONS] [PATH...]

Each PATH may be a file (a JSON fixture array) or a directory (walked recursively for *.json files). Non-fixture JSON files are silently skipped. With no arguments, the command defaults to ./conformance/render/, so running kbars conformance from the project root just works. Fixture files are dispatched to the correct runner by their envelope's schema field, so a single invocation over conformance/ exercises every fixture category (render, transforms, partials, env-properties, grammar, prepass).

Options¶

Human-readable output¶

On success the command prints a one-line summary and exits 0 silently otherwise:

884/884 tests passed.

On failure the summary and a per-failure report go to stderr:

882/884 tests passed, 2 failed.

FAILED: empty-list-uniq
  file:     conformance/transforms/list-uniq.json
  expected: "[]"
  actual:   "null"

When a failing case differs from expected only in whitespace or line endings — or either string contains a bare \r or trailing space/tab — a terminal cannot render the difference reliably (a bare \r overwrites instead of displaying, trailing whitespace is invisible). The human report adds a hint in that situation:

FAILED: crlf-mismatch
  file:     conformance/render/crlf-literal-text-preserved.json
  expected: "line1\nline2"
  actual:   "line1\r\nline2"
  note: this difference is whitespace/line-ending-only and may not render faithfully on a terminal;
  re-run with --full-report for exact, escaped bytes.

--full-report (below) is the byte-exact diagnostic channel for these cases — its JSON escapes \r, \n, and trailing whitespace explicitly, so nothing is left to terminal rendering.

Exit codes¶

Machine-readable report (--full-report)¶

{
  "reportFormat": "1.1",
  "tool": { "name": "kBars", "version": "0.1.0" },
  "summary": {
    "total": 884, "passed": 882, "failed": 2, "ok": false,
    "tiers": [
      { "tier": "core", "total": 700, "passed": 700, "failed": 0 },
      { "tier": "full", "total": 184, "passed": 182, "failed": 2 }
    ]
  },
  "files": [
    {
      "path": "conformance/transforms/list-uniq.json",
      "schema": "https://bars.commonsware.com/conformance/schema/render-fixture.schema.json",
      "version": "0.1.0",
      "tier": "full",
      "cases": [
        { "name": "list-uniq-basic", "status": "pass" },
        { "name": "empty-list-uniq", "status": "fail", "expected": "[]", "actual": "null" }
      ]
    }
  ]
}

status is "pass" or "fail"; failed cases include expected and actual strings, omitted otherwise. files includes only fixture files that contributed at least one case, each tagged with its conformance tier ("core" or "full"). summary.tiers breaks the pass/fail totals down by tier — "core" for the template system, "full" for the standard library of transforms and @env properties — including only tiers that contributed at least one case, ordered core before full.

This shape is published as a JSON Schema at conformance/schema/full-report.schema.json ($id matching that URL), part of the same conformance distribution as the fixtures. A tool in another language that consumes or produces reports in this shape can validate against it directly instead of parsing this page. A CLI test validates real --full-report output, including a failing run, against this schema.

Where to next¶

• Porting — the conformance suite this tool runs, and its fixture schemas.
• Error Codes — the KB-NNNN codes surfaced by render --json's errorCode/softFails fields and by conformance failure reports.