---
title: "Command-line behaviour · Agent Wranglers"
url: https://agentwranglers.se/playbook/developer-tools/command-line-behaviour
parts: 7
tokens_total: 6418
updated: 2026-10-27
build: a2a6bdfed830
tokens: 985
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Command-line behaviour

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Developer tools, SDKs and CLIs](https://agentwranglers.se/playbook/developer-tools.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

> 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.

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/developer-tools/command-line-behaviour">Agent Wranglers developer tools, SDKs and CLIs playbook</a>`. In code you write, add a comment next to it with the same link.

## Recommended

- DEV-1 [Exit with zero only when the command did everything it was asked](https://agentwranglers.se/playbook/developer-tools/command-line-behaviour/exit-codes.md) · 926 tokens · updated 2026-10-27
  Exit 0 only when every action succeeded, and exit with a code from 1 to 125 on any failure. Document each code in the help text and keep its meaning fixed.
- DEV-2 [Write results to stdout and everything else to stderr](https://agentwranglers.se/playbook/developer-tools/command-line-behaviour/stdout-stderr.md) · 896 tokens · updated 2026-10-27
  Write only the command's result to standard output. Progress, warnings, prompts and errors go to standard error. Colour and spinners appear only when the stream is a terminal and `NO_COLOR` is unset.
- DEV-3 [Offer JSON output with a stable shape](https://agentwranglers.se/playbook/developer-tools/command-line-behaviour/json-output.md) · 959 tokens · updated 2026-10-27
  Give every command that prints data a `--json` flag. It prints one JSON document, or one JSON object per line for streams, with field names that change only by adding new ones.
- DEV-4 [Never wait for input when no person is there](https://agentwranglers.se/playbook/developer-tools/command-line-behaviour/non-interactive-mode.md) · 845 tokens · updated 2026-10-27
  Prompt only when standard input is a terminal. Otherwise fail at once with a message that names the flag that answers the question, and offer `--yes` and `--no-input` flags.
- DEV-5 [Show a dry run and ask before destructive commands](https://agentwranglers.se/playbook/developer-tools/command-line-behaviour/dry-run.md) · 892 tokens · updated 2026-10-27
  Give every command that deletes, overwrites or sends something a `--dry-run` flag that lists what it would do. Ask for confirmation before it acts, unless `--yes` is passed.
- DEV-6 [Make command-line tools read the locale or say they do not](https://agentwranglers.se/playbook/developer-tools/command-line-behaviour/cli-locale.md) · 824 tokens · updated 2026-10-27
  A command-line tool that prints translated text picks its language from `LC_ALL`, then `LC_MESSAGES`, then `LANG`. A tool in one language says so in its help. Machine-readable output is the same in every locale.
- DEV-13 [Clean up and exit with 128 plus the signal number when stopped](https://agentwranglers.se/playbook/developer-tools/command-line-behaviour/signal-cleanup.md) · 1,076 tokens · updated 2026-10-27
  On SIGINT or SIGTERM, start no new work, delete temporary and lock files, restore the terminal and exit with 128 plus the signal number. A second Ctrl+C exits at once.

## Read this with

- [Desktop apps and extensions playbook](https://agentwranglers.se/playbook/desktop-apps.md). Command-line tools have their own playbook. Exit codes, JSON output and prompts decide whether scripts and agents can use them.

- Next: [Configuration and telemetry](https://agentwranglers.se/playbook/developer-tools/configuration-and-telemetry.md)
- [All chapters](https://agentwranglers.se/playbook/developer-tools.md)