Use the Sonde CLI

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