Developer tools, SDKs and CLIs playbook

A developer tools playbook for command-line tools, libraries and SDKs that other people build on. Their users are developers, CI jobs and AI agents, and all three read exit codes and output formats more closely than any screen.

It starts with how a command-line tool behaves. That means exit codes, output streams, JSON, prompts and signals. Then it covers configuration files and telemetry, help and shell completion, and update checks that never block a script. The last chapters cover versioning a library's public API and publishing releases with checksums, signatures and build provenance.

Desktop apps and browser extensions have their own desktop apps playbook. Web APIs that an SDK calls follow the API design playbook.

Chapters

1. Command-line behaviour

   Exit codes, clean output streams, JSON output, signal handling and no surprise prompts let scripts, CI jobs and AI agents use a command-line tool safely.

   • Recommended 7

2. Configuration and telemetry

   Read settings in one documented order from standard paths, take secrets from the environment, and let users switch telemetry off with one variable.

   • Required 1
   • Recommended 2

3. Help, completion and updates

   Give every command help with an example, ship shell completion, and check for new versions politely, never in scripts or CI.

   • Recommended 3

4. Libraries and SDKs

   Declare the public API, check every release against it, deprecate before removing and publish which language versions each release supports.

   • Recommended 4

5. Distribution

   Publish checksums, signatures and build provenance with every release, so users and package managers can prove the file came from your build.

   • Required 1
   • Recommended 1

All 19 rules on one page

This is a lot to check. An Expert can check it for you.

Related playbooks

• Update integrity

  In the Desktop apps and extensions playbook. Tools that update themselves need the same signed, verified updates as desktop apps.

• Releases

  In the Open source maintenance playbook. Most developer tools are published in the open. Release notes, tags and versions follow the open source rules.

• Changes over time

  In the API design playbook. An SDK wraps an API. Version the API and the SDK on the same promise, so neither breaks callers.

• Apps and command-line tools

  In the Localization playbook. Command-line tools print messages people read. Store and translate them as the apps do.