CLI reference

Getting the CLI

The CLI ships as one self-contained jar on Maven Central. It needs only Java 17 and never runs your application.

curl -O https://repo1.maven.org/maven2/io/github/tibyaan-org/tibyan-cli/0.3.0/tibyan-cli-0.3.0-jar-with-dependencies.jar

Invoke it as java -jar <jar> <command> [options]. To keep commands short, define a wrapper once. Every example below uses it.

TIBYAN="/path/to/tibyan-cli-0.3.0-jar-with-dependencies.jar"
tibyan() { java -jar "$TIBYAN" "$@"; }

$TIBYAN = "C:\path\to\tibyan-cli-0.3.0-jar-with-dependencies.jar"
function tibyan { java -jar $TIBYAN @args }

Commands at a glance

On any command, -h or --help prints usage (tibyan scan --help), and -V or --version prints the tool version. Running tibyan with no command prints the usage summary.

Exit codes

Every command uses one convention.

tibyan scan

Read a system from source and survey it. This is the resilient path: it walks the entire source tree, parses collect-and-continue, classifies every entity it can read, and names every file it cannot parse. It never aborts on one unparseable file, and it never emits a wrong binding.

tibyan scan <path> [--out <ir.json>] [--report <report.md>]

Exit codes: 0 the survey completed, whatever it discovered, including zero; 2 --out was given but the model did not validate; 3 the path is missing, is not a directory, or cannot be walked. For how to read the output, see Reading your survey.

tibyan scan /path/to/app                                      # survey to the console
tibyan scan /path/to/app --report report.md                   # shareable Markdown survey
tibyan scan /path/to/app --out app.ir.json                    # write the model (only if it validates)
tibyan scan /path/to/app --out app.ir.json --report report.md

tibyan generate

Generate a backend from a model file, or by scanning a path directly. Generating from a <path> uses the strict provider, not the resilient scan: it refuses any unparseable file or unresolvable binding rather than producing a partial artifact. Generation is deterministic: the same model in produces the same files out.

tibyan generate --backend <mcp|openapi> --out <dir> (--ir <ir.json> | <path>)

Exit codes: 1 unknown backend, or neither --ir nor a path was given; 2 the model did not validate; 3 provider or backend error.

tibyan generate --backend mcp     --ir app.ir.json --out ./generated
tibyan generate --backend openapi --ir app.ir.json --out ./generated
tibyan generate --backend openapi --out ./generated /path/to/app   # scan directly (strict)

tibyan attest

Two actions on your committed tibyan/attestations.json. The tool never writes a claim's words in either action: the meaning is always the human's. The concepts are in Attestation.

tibyan attest <path> [--date <yyyy-mm-dd>]
tibyan attest <path> --confirm <target> --by <name>

Stamping (the default action)

Computes the structural fingerprint of each entry's slice over the current code and writes it back, with --date optionally stamping the assertion date. This is the only path that stamps a fingerprint, so a fingerprint always arrives together with the code it pins. A hand-authored entry without one is refused at intake rather than silently completed.

tibyan attest /path/to/app --date 2026-09-01

Confirming a draft

An entry whose origin is ai-draft is a proposal, not a claim. It ships nothing. Confirming it is the human act that turns it into a claim:

tibyan attest /path/to/app \
  --confirm "com.example.TenantServiceImpl#getAllByFilter(String,Integer)" \
  --by a.reviewer

That rewrites exactly that entry's origin to ai-drafted-human-confirmed and records you in assertedBy. Then stamp it and re-scan. There is no confirm-all: a team with ten drafts reviews ten drafts.

Exit codes: 0 the file was stamped, or the named draft was confirmed; 1 --confirm did not apply (no such target, not a draft, or no --by); 3 the path is missing or cannot be walked.

tibyan validate

Validate a model JSON file against the semantic rules, without generating anything. Useful before feeding a hand-edited or externally produced file to generate.

tibyan validate --ir app.ir.json

Exit codes: 0 valid, and a one-line summary prints; 2 invalid, and the located errors print; 3 the file cannot be read or parsed.

tibyan version

Prints the tool version and the model schema version. tibyan --version prints just the tool line.

A typical session

tibyan scan /path/to/app --report report.md        # 1. what is operable, what is refused, and why
tibyan scan /path/to/app --out app.ir.json         # 2. write the model when the survey looks right
tibyan validate --ir app.ir.json                   # 3. optional; generate validates too
tibyan generate --backend mcp     --ir app.ir.json --out ./generated
tibyan generate --backend openapi --ir app.ir.json --out ./generated

For most adopters the Maven plugin performs these steps automatically during the build. The CLI and the plugin generate identical output for the same source.