cli-reference.mdx

title	Use the Sonde CLI
description	Canonical command behavior for the Sonde reference CLI, including outputs and edge cases.

Purpose

Use this page as the authoritative command contract for the Sonde reference CLI (@sonde-sh/sonde). For normative contract semantics, read Sonde and Manifest first.

The reference CLI is intentionally focused on three outcomes:

1. Generate manifest contracts from existing CLIs.
2. Evaluate CLIs against those contracts and return a report.
3. Stay self-compliant by exposing Sonde's own manifest contract.

Inputs

• CLI arguments (<command>, <cli>, flags).
• Local sondage.manifest.json for run, score, and serve.
• JSON line requests on stdin for serve.

Outputs

• Exit code 0 on success, 1 on parse/command failure.
• Human-readable text by default.
• JSON payloads for command success/failure when --json is active.
• serve responses are always JSON lines.
• JSON command payloads include apiVersion.

Commands

sonde generate <cli> [--json]

Generate sondage.manifest.json from <cli> --help and subcommand help output.

Behavior notes

• Requires exactly one <cli> argument.
• Writes manifest to sondage.manifest.json in current working directory.
• Probes help commands with a 10s timeout per probe.

sonde evaluate <cli> [--json] [--save [path]]

Evaluate a third-party CLI and return the canonical weighted report (0–100) without a local manifest file.

Behavior notes

• Requires exactly one <cli> argument (the CLI binary name to evaluate).
• Generates a manifest in memory (does not write sondage.manifest.json).
• Runs the same scoring logic as score: two --help runs, then weighted report.
• Use when you want a one-off evaluation or CI check without committing a manifest.
• --save [path] (evaluate only): write the evaluation report as JSON to a file. If path is omitted, defaults to <cli>.json in the current directory. Directories are created if needed.

When to use evaluate vs score

• evaluate: No local manifest. Good for trying a CLI, CI pipelines, or generating a report to publish later.
• score: Requires sondage.manifest.json in the current directory. Good for validating an existing manifest or repeat checks against a fixed contract.

sonde manifest [--json]

Print Sonde's own Sondage manifest as a reference implementation payload.

Behavior notes

• Does not require <cli>.
• Does not require local sondage.manifest.json.
• Returns a deterministic manifest payload suitable for automation checks.

sonde run <cli> [--json]

Run deterministic diagnostic checks using local manifest settings.

Behavior notes

• Requires local sondage.manifest.json.
• Executes manifest.cli.binary --help under the hood.
• May auto-add preferred flags (--json, and one non-interactive flag) if available in manifest options.
• <cli> is validated and echoed in output, but command execution uses manifest.cli.binary.

sonde score <cli> [--json]

Evaluate a CLI and return the canonical weighted report (0-100).

Behavior notes

• Requires local sondage.manifest.json.
• Performs two runs of manifest.cli.binary --help.
• Uses scoring engine over both run results and returns the full evaluation report payload.
• <cli> is validated and echoed in output, but command execution uses manifest.cli.binary.

sonde publish <cli> [--json]

Optionally submit an evaluation report to a Sonde web endpoint.

Behavior notes

• Requires SONDE_PUBLISH_URL and SONDE_PUBLISH_TOKEN.
• Runs score semantics and posts a normalized payload plus full report details.
• Intended as an optional follow-up step after local evaluation.

sonde serve [--json]

Start JSON-line tool protocol server backed by sondage.manifest.json.

Behavior notes

• Requires local sondage.manifest.json.
• This is an integration capability, not required for core Sonde evaluation flow.
• Supports methods: tools/list, tools/call.
• Announces readiness:
  • --json: {"ok":true,"command":"serve","apiVersion":"1.0.0","protocolVersion":"1.0.0","status":"ready"}
  • default: serve ready
• Each input line is parsed as JSON request.
• Invalid JSON lines return structured error with id: null.

Global flags

• --json
  • Enables JSON success/failure payloads for generate, evaluate, run, score.
  • Parse errors still write JSON to stderr when --json is present.
• --save [path]
  • evaluate only. Write the evaluation report to a JSON file. Default path is <cli>.json if omitted.
• --help, -h
  • Works globally and per-command (sonde run --help).
  • Returns plain usage text (not JSON).
• --version, -v
  • Works only at top level with no command args.
  • Returns plain version text (not JSON).

Parser and argument constraints

• Usage:
  • sonde <command> [options]
  • sonde manifest [--json]
  • sonde serve [--json]
  • sonde <generate|evaluate|run|score|publish> <cli> [--json]
  • sonde evaluate <cli> [--json] [--save [path]]
• Unknown commands fail with usage error.
• Extra positional args fail (Unexpected extra arguments for '<command>').
• Unknown flags are not special-cased and may be treated as unexpected extra args.

Versioning and compatibility

• Manifest version is semantic versioning and must follow major.minor.patch.
• Current supported manifest major version is 1; other major versions return UNSUPPORTED_VERSION.
• JSON command payloads include apiVersion so consumers can parse envelopes safely.
• Score reports include manifestVersion and generatedAt.
• Serve protocol messages include protocolVersion.

Deterministic examples

JSON success: generate

{
  "ok": true,
  "apiVersion": "1.0.0",
  "command": "generate",
  "cli": "vercel",
  "result": {
    "commandCount": 3
  }
}

JSON success: run

{
  "ok": true,
  "apiVersion": "1.0.0",
  "command": "run",
  "cli": "supabase",
  "result": {
    "status": "ok"
  }
}

JSON success: score

{
  "ok": true,
  "apiVersion": "1.0.0",
  "command": "score",
  "cli": "vercel",
  "result": {
    "manifestVersion": "1.0.0",
    "generatedAt": "2026-03-05T00:00:00.000Z",
    "total": 96
  }
}

JSON success: evaluate

Same shape as score; use when you do not have a local manifest.

{
  "ok": true,
  "apiVersion": "1.0.0",
  "command": "evaluate",
  "cli": "vercel",
  "result": {
    "manifestVersion": "1.0.0",
    "generatedAt": "2026-03-05T00:00:00.000Z",
    "total": 85,
    "jsonSupport": true,
    "interactivePrompts": false,
    "notes": "..."
  }
}

JSON error: invalid command with --json

{
  "ok": false,
  "apiVersion": "1.0.0",
  "error": {
    "message": "Usage: sonde <command> [options]"
  }
}

JSON error: missing manifest for run

{
  "ok": false,
  "apiVersion": "1.0.0",
  "command": "run",
  "cli": "supabase",
  "error": {
    "message": "MISSING_FILE: Manifest file not found"
  }
}

Edge cases

• sonde --json --help prints plain text help.
• sonde run --version does not print version; it is treated as missing <cli>.
• serve does not accept positional args (Usage: sonde serve [--json]).
• manifest does not accept positional args (Usage: sonde manifest [--json]).
• Interactive output patterns (for example prompts like [y/n]) mark run results as non-deterministic.

See also

• Quickstart
• AI-Native CLI Requirements
• Serve Protocol
• Troubleshooting
• Scoring 100 Guide