Start with Sonde in 5 Minutes

Purpose

Get from zero to a reproducible manifest workflow in a few commands using the reference CLI.

Mental model

• generate creates the standardized contract artifact (sondage.manifest.json).
• evaluate runs the same scoring as score but without a local manifest (generates one in memory). Use for one-off checks or CI.
• score is the canonical CLI evaluation report against a local manifest.
• manifest prints Sonde's own reference Sondage manifest (self-compliance check).
• run is a deterministic diagnostic command.
• publish is an optional step to submit the report to the website API.

Inputs

• Node.js and npm/pnpm installed.
• A target CLI available in PATH (recommended local fixture: cli-good).
• Write access in current working directory.

Outputs

• sondage.manifest.json in current directory.
• Deterministic run output.
• Scoring output with a 0-100 score.

Steps

1) Install or run directly

npx @sonde-sh/sonde --help

2) Generate manifest

sonde generate cli-good --json

Expected output shape:

{
  "ok": true,
  "apiVersion": "1.0.0",
  "command": "generate",
  "cli": "cli-good",
  "result": {
    "manifest": {
      "version": "1.0.0"
    },
    "outputPath": "sondage.manifest.json",
    "commandCount": 2
  }
}

3) Inspect Sonde reference manifest

sonde manifest --json

Expected output shape:

{
  "ok": true,
  "apiVersion": "1.0.0",
  "command": "manifest",
  "result": {
    "version": "1.0.0",
    "cli": {
      "name": "sonde",
      "binary": "sonde"
    }
  }
}

4) Run deterministic check

sonde run cli-good --json

Expected output shape:

{
  "ok": true,
  "apiVersion": "1.0.0",
  "command": "run",
  "cli": "cli-good",
  "result": {
    "ok": true,
    "exitCode": 0
  }
}

5) Compute score

sonde score cli-good --json

Expected output shape:

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

Edge cases

• If target CLI is missing, generation fails with execution error.
• run and score require sondage.manifest.json in current directory.
• If CLI output looks interactive, run quality decreases and score may drop.
• For stable local docs/testing, prefer cli-good and compare against cli-ok / cli-bad to understand scoring trade-offs.
• Manifest loading fails with UNSUPPORTED_VERSION when manifest major version is not supported.

Next: Sonde and Manifest to understand the model and contract.

See also

• CLI Reference
• Scoring 100 Guide
• Troubleshooting