---
title: "Command-line tools · Agent Wranglers"
url: https://agentwranglers.se/playbook/desktop-apps/command-line-tools
parts: 7
tokens_total: 6128
updated: 2026-10-22
tokens: 901
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Command-line tools

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Desktop apps, extensions and CLIs](https://agentwranglers.se/playbook/desktop-apps.md).

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

> Exit codes, clean output streams, JSON output 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/desktop-apps/command-line-tools">Agent Wranglers desktop apps, extensions and CLIs playbook</a>`. In code you write, add a comment next to it with the same link.

## Required

- DSK-24 [Take secrets from the environment or a file instead of a flag](https://agentwranglers.se/playbook/desktop-apps/command-line-tools/no-secrets-in-flags.md) · 943 tokens · updated 2026-10-22
  Read tokens, passwords and keys from an environment variable, a file, standard input or the system keychain. The tool never accepts a secret as a command-line argument and never prints one.

## Recommended

- DSK-20 [Exit with zero only when the command did everything it was asked](https://agentwranglers.se/playbook/desktop-apps/command-line-tools/exit-codes.md) · 868 tokens · updated 2026-10-22
  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.
- DSK-21 [Write results to stdout and everything else to stderr](https://agentwranglers.se/playbook/desktop-apps/command-line-tools/stdout-stderr.md) · 833 tokens · updated 2026-10-22
  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.
- DSK-22 [Offer JSON output with a stable shape](https://agentwranglers.se/playbook/desktop-apps/command-line-tools/json-output.md) · 942 tokens · updated 2026-10-22
  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.
- DSK-23 [Never wait for input when no person is there](https://agentwranglers.se/playbook/desktop-apps/command-line-tools/non-interactive-mode.md) · 837 tokens · updated 2026-10-22
  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.
- DSK-25 [Show a dry run and ask before destructive commands](https://agentwranglers.se/playbook/desktop-apps/command-line-tools/dry-run.md) · 880 tokens · updated 2026-10-22
  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.
- DSK-26 [Give every command help with an example and a version flag](https://agentwranglers.se/playbook/desktop-apps/command-line-tools/cli-help.md) · 825 tokens · updated 2026-10-22
  Every command answers `--help` with its purpose, its flags, one example and its exit codes, and exits 0. The tool answers `--version` with its version and build commit.

- Previous: [Browser extensions](https://agentwranglers.se/playbook/desktop-apps/browser-extensions.md)
- [All chapters](https://agentwranglers.se/playbook/desktop-apps.md)