cli-qa

Capture stdout, stderr, and exit codes for CLI golden-file QA.

33|5|Updated Feb 28, 2026
One-click install
npx skills add https://github.com/kylesnowschwartz/ralph-ban --skill cli-qa
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: cli-qa
Source: https://github.com/kylesnowschwartz/ralph-ban/tree/main/skills/cli-qa
Command: npx skills add https://github.com/kylesnowschwartz/ralph-ban --skill cli-qa

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you verify that a CLI tool behaves exactly as specified by capturing stdout, stderr, and exit codes and comparing them against a golden expectation with volatile-field redaction.

Core Features & Use Cases

  • Deterministic command execution: Builds and runs the correct binary from the worktree to ensure the evidence reflects the code under test.
  • Three-channel evidence capture: Records stdout, stderr, and exit code separately to preserve what the spec can assert.
  • Golden-file comparisons with redaction: Compares observed output to fixtures after normalizing timestamps, PIDs, temp paths, ANSI escapes, and other volatile fields.
  • QA workflows for changed surfaces: Uses diffs/logs to infer which subcommands, flags, or output formats are likely impacted when no scope is provided.
  • Operational rigor: Covers environment levers for reproducibility, PTY vs non-TTY divergence, and signal-handling assertions for deterministic shutdown behavior.

Quick Start

Run the CLI with representative inputs, capture stdout/stderr/exit into a timestamped .agent-history/oracle/<card-id>/... folder, redact volatile fields, and diff the redacted stdout against the corresponding golden fixture.

Frequently Asked Questions about cli-qa

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I verify CLI behavior using stdout, stderr, and exit codes?

Verifying CLI behavior requires driving a command-line binary with representative inputs, capturing stdout, stderr, and exit codes separately, and comparing them against expected output with volatile fields redacted. This ensures deterministic transcripts for end-to-end QA.

How do I handle volatile data like timestamps and temp paths when comparing command-line output?

Redacting volatile fields normalizes timestamps, PIDs, temp paths, and ANSI escapes before comparing observed output to golden fixtures. This byte-exact redaction scheme ensures deterministic comparisons even when the underlying runtime values change between executions.

What is the best way to test CLI error handling and exit-code semantics?

Testing CLI error handling and exit-code semantics involves capturing the exit code immediately after execution and recording stderr separately from stdout. This three-channel evidence capture preserves what the specification can assert during end-to-end QA.

Can I use golden files for testing large or structurally rich command-line outputs?

Golden-file comparisons support testing large or structurally rich CLI outputs by diffing redacted stdout against expected fixtures. This approach applies to QA workflows for subcommands, flags, and output formats without requiring manual output inspection.

Does CLI testing work for PTY vs non-TTY divergence and signal handling?

CLI testing covers operational rigor including PTY vs non-TTY divergence and signal-handling assertions for deterministic shutdown behavior. Normalizing environment variables ensures reproducibility across different terminal environments during command execution.