Sonde

Sonde defines a stable manifest contract for AI-native CLI workflows and provides tooling to generate, validate, and score against that contract. The CLI in this repository is the reference implementation used to produce standardized artifacts for developers, agents, and automation.

Product scope

Sonde CLI has three primary goals:

1. Generate the manifest JSON contract that target CLIs should expose from their-cli manifest, by exploring command/help output.
2. Evaluate a target CLI against the manifest rules and produce a machine-readable report.
3. Be Sonde-compliant itself by exposing its own sonde manifest contract.

Integration commands (publish, serve) are optional capabilities around that core workflow.

Canonical docs

The canonical documentation source is:

• apps/web/content/docs

Start here:

• Docs index
• Sonde
• Manifest
• AI-native CLI requirements
• Quickstart
• CLI reference
• Serve protocol
• Scoring 100 guide
• Troubleshooting

Manifest contract first

• The manifest contract is versioned in sondage.manifest.json via version.
• Command JSON envelopes include apiVersion to keep integrations parse-safe.
• Serve protocol readiness and responses include protocolVersion.
• Score reports include manifestVersion and generatedAt for compatibility and freshness tracking.

Reference implementation (CLI)

npm install -g @sonde-sh/sonde

Or run directly:

npx @sonde-sh/sonde --help

Quick command view

sonde generate <cli> [--json]
sonde evaluate <cli> [--json] [--save [path]]
sonde score <cli> [--json]
sonde manifest [--json]
sonde run <cli> [--json]
sonde publish <cli> [--json]
sonde serve [--json]

For complete behavior, outputs, and edge cases, use the canonical CLI reference. For normative contract semantics, start with Sonde and Manifest.

Examples and fixtures

• Runnable compatibility fixtures live in examples/cli-good, examples/cli-ok, and examples/cli-bad.
• Use runnable fixtures for deterministic local demos and test automation.

Packages

• @sonde-sh/sonde: CLI binary (sonde)
• @sonde-sh/spec: STM schema, types, and manifest loading/validation
• @sonde-sh/generator: help-text parsing and manifest generation
• @sonde-sh/runtime: deterministic command execution and tool execution
• @sonde-sh/scoring: weighted (0-100) scoring engine for CLI behavior

Versioning and compatibility

• Current supported manifest major version is 1; loading a different major returns UNSUPPORTED_VERSION.
• Manifest versioning follows semantic versioning (major.minor.patch).
• Protocol version fields are intended as machine-consumable compatibility guards.

Local development

Prerequisites:

• Node.js 18+
• pnpm 9+

Install and validate:

pnpm install
pnpm check-types
pnpm lint
pnpm test
pnpm build

Run the local CLI build:

pnpm --filter @sonde-sh/sonde build
node packages/sonde-cli/dist/src/bin.js --help

Release workflow

This repository uses Changesets:

pnpm changeset
pnpm version-packages
pnpm release

Release PRs and npm publish are automated via GitHub Actions.

Report publishing

Developers can publish generated reports to the web app when it exposes publish APIs.

Required environment variables for sonde publish:

• SONDE_PUBLISH_URL (example: https://your-site.vercel.app/api/reports/publish)
• SONDE_PUBLISH_TOKEN (shared token expected by the publish API)

Web app environment variables for moderation:

• BLOB_READ_WRITE_TOKEN (Vercel Blob store token)
• SONDE_PUBLISH_TOKEN (same shared publish token)
• SONDE_REPORTS_ADMIN_TOKEN (maintainer-only token for approvals)