3-cli-process — Claude Code rule: CLI process, channels and exit codes
3-cli-process sets the conventions for a CLI process: how it shuts down, which channel gets which output, and what exit code it returns.
MIT ★ 571 updated 2026-10-29
.claude/rules/3-cli-process.mdWhat 3-cli-process does
A scoped rule for the command-line entry point. It loads for src/cli.ts and src/presentation/**/*.ts, so the rest of the repo is left alone.
Most of it is about shutdown. A floating promise or a bare unref() dies with the process, so background work has to go through an online command (ONLINE_COMMAND_PATHS in cli.ts), sit behind a timeout, or run detached. The fast path stays offline: read the cache, print, return. Side effects get asserted against the built binary, either in e2e or with pnpm smoke.
Output is split by channel: stdout for results and confirmations, stderr for debug lines, warnings and errors. A skipped or conflicting step is reported as warn rather than error. CLIOutput picks the level; rendering belongs to presentation/display/, decisions stay in the use case. Only two exit codes are allowed, 0 and 1, and a domain failure becomes a code through errorHandler.handle. Code under contexts/, kernel/ and runtime/ never calls process.exit — the biome-plugins/no-process-exit.grit plugin enforces that, and without it you are back to catching it in review.
What it helps with
- Route command output between
stdoutandstderr - Keep background work alive until the process exits
- Assign an exit code to a domain failure
- Ban
process.exitinsidecontexts/,kernel/andruntime/ - Verify a side effect against the built binary
Example prompts for the agent
- Add a
synccommand tosrc/cli.tsand route its output the way3-cli-processsays - Audit
src/cli.tsfor floating promises andunref()calls nobody awaits - Why did the command exit with code 1? Walk the error handling against
3-cli-process
How to install 3-cli-process
Manually: put the files in place
.claude/rules/3-cli-process.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/3-cli-process.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/3-cli-process.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/3-cli-process.mdManually: put the files in place
.clinerules/3-cli-process.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about 3-cli-process
How do I install 3-cli-process in Claude Code?
Place the rule file at .claude/rules/3-cli-process.md inside the project.
What does 3-cli-process do?
It sets the conventions for the CLI process: shutdown, output channels, formatting and exit codes.
Does 3-cli-process work outside Claude?
Yes. The same rule ships as .cursor/rules/3-cli-process.mdc for Cursor and as .github/instructions/3-cli-process.instructions.md for GitHub Copilot.
Source text
3-cli-process.md · MIT
--- description: Apply to the process, its channels and its exit codes; the CLI exits when the action resolves. paths: - "src/cli.ts" - "src/presentation/**/*.ts" --- # The CLI Process ## Exit - Never fire and forget: `unref()` and floating promises die with the process. - Deferred work rides an online command (`ONLINE_COMMAND_PATHS` in `cli.ts`), awaits behind a timeout, or runs detached. - The hot path is offline: read cache, print, return. - Assert a side effect against the built binary (e2e or `pnpm smoke`). ## Channels - `stdout`: info, success, results. - `stderr`: debug, warnings, errors. - A conflict or skip is `warn`, never `error`. - One-line final summary. ## Formatting - `CLIOutput` routes by level, nothing else. - Rendering: `presentation/display/`. Deciding: the use case. ## Exit codes - `0`: did what was asked. - `1`: thrown error, unhealthy `doctor`, guard needing a TTY. - `errorHandler.handle` alone turns a domain failure into a code. - A command may exit on a pre-use-case refusal: missing flag, non-interactive guard. - Nothing under `contexts/`, `kernel/`, `runtime/` calls `process.exit` (`biome-plugins/no-process-exit.grit`).
© ai-driven-dev · MIT · ai-driven-dev/framework