What is better-cli AGENTS.md?

A set of project instructions for building command-line tools, including how they print results, report errors, handle prompts, and define options.

Use it when creating or changing a command-line interface, especially its output format, error messages, exit codes, prompts, flags, and configuration rules.

It helps command-line programs behave consistently and remain usable in scripts, terminals, and automated environments.

better-cli AGENTS.md — Instructions file by yogin16

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/yogin16/better-cli/agents-md

Clone the repo

git clone --depth 1 https://github.com/yogin16/better-cli

Made for: Codex, OpenCode.

Per session 361 This file is loaded in full into every session.

When invoked 361 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.00361	$0.00361
Opus 5	$0.00180	$0.00180
Sonnet 5	$0.00072	$0.00072
Haiku 4.5	$0.00036	$0.00036

Measured 2d ago against content hash 2c4a854056f8, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

better-cli AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

AGENTS.md · 33 lines

What it actually says

CLI Development Guidelines

When building or improving any CLI tool in this project, follow these principles:

Output Design

stdout for data only, stderr for everything else (errors, warnings, progress)
Support --json with a consistent envelope: {"status": "ok|error", "data": {...}}
Output must guide the next action — success shows "Next steps", failure shows "Fix"
No ANSI escape codes when stdout is not a TTY; respect NO_COLOR env var

Error Handling

Exit 0 on success, semantic non-zero codes on failure (2=usage, 3=not found, 4=permission, 75=transient)
Errors include: what went wrong, context, fix command, docs link
Structured errors in JSON mode: {"code": "AUTH_EXPIRED", "message": "...", "fix": "...", "transient": false}

Interactivity

Every interactive prompt must have a flag equivalent (--yes, --force, --name=value)
Never hang waiting for input when stdin is not a TTY
Progress bars and spinners go to stderr only

Flags and Arguments

Prefer flags over positional arguments for clarity
Configuration precedence: flags > env vars > project config > user config > defaults
Never accept secrets via flags (use env vars or --password-file)

Composability

Support --fields to limit output columns
Support --quiet for minimal output (IDs only)
Support --dry-run for mutating commands
Create commands output the created resource identifier

For the full guide, see the better-cli skill: SKILL.md

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

2d ago First seen · 33 lines · 361 tokens per session scan A 2c4a854056f8

Subscribe to this mod's changes

better-cli AGENTS.md is an instructions file published in the GitHub repository yogin16/better-cli (11 stars, last pushed 5mo ago), licensed Apache-2.0. It adds 361 tokens to every session, about $0.0018 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

codex AGENTS.md

AGENTS.md instructions for openai/codex, covering rust/codex-rs, the codex-core crate, code review rules, crate api surface and model visible context.

openai/codex · 5,182 tokens

vscode buildNext.instructions.md

Working notes and architecture documentation for the new esbuild-based build system in build/next. Use when making changes to the new build pipeline (transpile/bundle commands, NLS plugin, source-map handling, resource copying, or self-hosting watch tasks).

microsoft/vscode · 6,785 tokens

better-cli AGENTS.md