CLI reference

CLI reference

Every command is read-only. Every command accepts --json.

mestre-yoda help
mestre-yoda version   [--json]
mestre-yoda handshake [--json]
mestre-yoda profiles  [--json]
mestre-yoda describe  <profile> [--json]
mestre-yoda inspect   [--root <directory>] [--json]
mestre-yoda recommend [--root <directory>] [--json]
mestre-yoda check     <profile> [--root <directory>] [--json]
mestre-yoda plan      <profile> [--root <directory>] [--json]
mestre-yoda validate  [--json]

Global options

Option	Meaning
--json	Emit the protocol envelope instead of human text
--root <dir>	The repository to analyze. Defaults to the current working directory
--help, -h	Print usage and exit, whatever the command

--root needs a path immediately after it. If the next token starts with --, or there is no next token, the command fails with The --root option requires a directory.

An unrecognized flag is an error rather than something quietly ignored, which means a typo like --jsom fails loudly instead of producing human output your parser cannot read.

Exit codes

Code	Meaning
0	The command ran. For check, this does not mean the project is compliant
2	The request was invalid: unknown command, unknown profile, bad option, unreadable root

There is no exit code for "not compliant". A failing check exits 0 with compliant: false in the payload. Gating in a pipeline is your policy decision, and CI integration shows how to wire it.

help

Prints usage. Also what you get when you pass --help to anything, and what is appended to stderr on a human-mode error.

version

mestre-yoda version

Mestre Yoda 0.1.0

The provider version, not the protocol version. handshake reports both.

handshake

The discovery call. An orchestrator should run this first and refuse to continue if the protocol major is one it does not know.

mestre-yoda handshake

Provider: mestre-yoda@0.1.0
Protocol: 1.0.0
Mode: read-only
Capabilities: profiles.list, profiles.describe, project.inspect, project.recommend, project.check, project.plan, catalog.validate

The JSON form adds mutations: false, which is the machine-readable version of the read-only promise.

profiles

Lists the catalog.

mestre-yoda profiles

dotnet-modular-react-postgresql@1.0.0: .NET Modular + React + PostgreSQL

JSON returns id, name, version, and digest for each profile. Use it to detect that a profile changed without reading the whole manifest.

describe <profile>

The full public manifest: stack, principles, optional capabilities, policy and recipe and gate references, and every rule.

mestre-yoda describe dotnet-modular-react-postgresql

.NET Modular + React + PostgreSQL (dotnet-modular-react-postgresql@1.0.0)
Golden Path for ASP.NET Core .NET 10 APIs built as a modular monolith, with React applications and PostgreSQL.
Rules: 21
Digest: sha256:89963b03fac95b7af4972176a46b92143948ddf280b3bc627d53539af797b56f

The human form is a summary. Use --json to get the whole manifest. The internal directory field is stripped before output, so a consumer never learns where the catalog lives on disk.

An unknown id fails with exit code 2 and Unknown Golden Path profile: <id>.

inspect [--root <dir>]

Observation without judgement. No profile is involved, so nothing here is right or wrong, only present or absent.

mestre-yoda inspect --root ~/code/my-api

Project: /home/you/code/my-api
Files: 412
✓ apiVersioning
✓ applicationLayer
· architectureTests
✓ authorizationPolicies
· defaultDeny
...

✓ means found, · means not found. The JSON form adds an inventory block:

Field	Meaning
files	Files walked, after skipping ignored directories
inspectedTextFiles	Files whose contents were read
inspectedBytes	Total bytes read
skippedSymlinks	Every symbolic link encountered, by relative path

skippedSymlinks is worth reading when a result looks wrong. A repository that keeps its source behind a symlink will inspect as nearly empty, and this field is where that shows up.

This is the only command that touches foreign files. Its limits are in the security model.

recommend [--root <dir>]

Ranks every profile in the catalog against the repository.

mestre-yoda recommend --root ~/code/my-api

Profile: dotnet-modular-react-postgresql@1.0.0
Stack confidence: 100%
Conformity: 77%

Confidence is computed from three signals only: modularDotnet, reactWeb, and postgresEfCore. Each contributes a third. It answers whether this standard is the right one for this repository, which is a different question from how well the repository currently complies.

Ranking is by confidence, then conformity, then alphabetically by id, so the order is stable across runs. The JSON form returns the full candidates array, not only the winner. With one profile in the catalog, recommended is always that profile, and the number that matters is its confidence.

check <profile> [--root <dir>]

The compliance report.

mestre-yoda check dotnet-modular-react-postgresql --root ~/code/my-api

Profile: dotnet-modular-react-postgresql@1.0.0
Status: not compliant
Score: 77%
Rules: 16 passed, 5 pending, 2 blocking
- [blocking] api.version-v1: Version public routes under /api/v1 and document the evolution policy.
- [blocking] security.default-deny: Set an authenticated FallbackPolicy and grant anonymous access only where it is declared.

Human output lists only failures, because the passing rules are rarely what you came for. JSON returns every rule with passed, signal, expected, observed, and remediation, which is what you want when rendering a dashboard or diffing two runs.

Status depends only on blocking failures. Score is severity-weighted. The arithmetic is in Scoring and compliance.

plan <profile> [--root <dir>]

The failures, ordered for whoever has to do the work.

mestre-yoda plan dotnet-modular-react-postgresql --root ~/code/my-api

Plan: sha256:e58b0438750d3f3a8be336f57f383f24d36c7b67c3028912428be06f53f7aa84
Mode: read-only
Tasks: 5
1. [blocking] Version public routes under /api/v1 and document the evolution policy.
2. [blocking] Set an authenticated FallbackPolicy and grant anonymous access only where it is declared.
3. [required] Add versioned migrations and validate them before deployment.

Sorted by severity, then by rule id. A compliant repository produces an empty task list, which is a valid plan rather than an error.

Each task in JSON carries order, ruleId, severity, action, and requiresHumanDecision, the last being true for blocking tasks. The envelope also carries readOnly: true and effects: [], always.

validate

Checks the catalog itself, with no repository involved. Every manifest is parsed and validated, every referenced policy, recipe, and gate file must exist and must match the safe reference pattern, rule ids must be unique, and every signal must be one the code implements.

mestre-yoda validate

Catalog is valid: 1 profile(s).

Run it after editing the catalog. It is also part of npm run verify.

Error output

Human mode writes Error: <summary> to stderr, followed by the usage text, and exits 2.

With --json, the failure envelope goes to stderr instead:

{
  "protocolVersion": "1.0.0",
  "provider": "mestre-yoda",
  "providerVersion": "0.1.0",
  "command": "describe",
  "status": "failure",
  "error": {
    "code": "INVALID_REQUEST",
    "summary": "Unknown Golden Path profile: missing-profile."
  }
}

Failure summaries never carry local paths, stack traces, or content from the analyzed project. A test asserts that the summary contains no stack frame, so a regression here fails the build.

Note that --json is honored for error reporting even when the argument parse itself failed, so a malformed command still gives a parser a JSON envelope rather than prose.