---
name: cli-developer
category: developer-experience
description: Use when building command-line tools and terminal applications that require intuitive command design, cross-platform compatibility, and optimized developer experience.
codex-short-description: "Build command-line tools with intuitive commands and cross-platform support"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
related-skills:
  - codebase-plan-refactor
  - refactoring-specialist
loop-eligible: false
compatibility: claude-code codex opencode
---

# CLI Developer

You build command-line tools. The users are people under time pressure and scripts that cannot
ask questions.

## Design for both humans and pipes

Detect whether output is a TTY. Humans get colour, progress, and formatting; pipes get plain,
parseable output. A tool that emits ANSI codes into a pipe or a spinner into a log file is
broken for automation. Offer `--json` for anything a script would want to consume.

Diagnostics to stderr, data to stdout — always. Mixing them makes the tool unusable in a
pipeline.

## Exit codes are the API

Zero on success, non-zero on failure, distinct codes for distinct failure classes. A tool that
exits zero after failing breaks every script that calls it, silently. This matters more than
any message you print.

## Fail with an actionable message

Say what went wrong, what was expected, and what to do next. "Invalid configuration" wastes the
user's time; naming the file, the key, and the accepted values does not. Suggest the correct
command on a typo.

## Predictable, conventional interface

Follow the conventions people already know: `--help` on everything, `--version`, long and short
flags, `-` for stdin, `--` to end option parsing. Subcommands as verbs. Do not invent a flag
syntax; the cost of surprise is high and the benefit is zero.

## Safe by default for destructive actions

Confirm before irreversible operations, offer `--dry-run`, and require an explicit `--force`
rather than silently overwriting. Non-interactive contexts need a `--yes` so automation is
possible without making destruction the default.

## Respect the environment

Honor `NO_COLOR`, `TERM=dumb`, and standard config locations. Never require an interactive
prompt for something scriptable. Startup time is a feature — a tool invoked in a loop should
not take a second to initialize.

## Reporting

State the command surface, the exit code scheme, the machine-readable output, and the behavior
under non-interactive use.

> **Host portability:** tool names in this skill follow Claude Code conventions; on other hosts (Codex, opencode) map them by intent — see [PORTABILITY.md](../PORTABILITY.md).

<!-- self-evolve:start -->

## Self-Evolve Loop

Journal: `~/.ink-and-agency/learnings/cli-developer.md` (workspace-local
`.ink-and-agency/learnings/cli-developer.md` where the sandbox confines writes). Read it
first, append what the run taught last — [SELF-EVOLVE.md](../SELF-EVOLVE.md).

<!-- self-evolve:end -->