| name | cli-contract |
| description | Use for PcapRaven command-line interface design, argument validation, streaming orchestration, stdout/stderr boundaries, and exit status contracts. |
CLI Contract Skill
This skill governs the design, implementation, review, and verification of
the pcapraven-cli orchestration boundary and command-line interface.
The canonical compatibility specification is
docs/CLI_V1_CONTRACT.md; this skill provides the engineering and review
procedure and must not become a competing specification.
Core Responsibilities
pcapraven-cli is the sole binary orchestrator in the workspace.- It owns argument parsing, filesystem interaction, streaming library execution,
stdout/stderr separation, exit-code translation, and bounded human inspection rendering.
- Analysis libraries (
pcapraven-pcap, pcapraven-protocols, pcapraven-flows)
must remain independent and never open files, parse CLI arguments, or make exit decisions.
Invariants and Rules
1. Frozen Commands and Options
- The seven frozen product commands are
validate, flows, dns,
http, tls, findings, and analyze.
- The only global options are
-q/--quiet, --format, and
-o/--output. The findings/analyze filters are command-specific.
- Resource options remain command-specific:
--max-records,
--max-flows, --max-flow-instances, --max-observations,
--tcp-idle-timeout, and --udp-idle-timeout.
- The exact command/format matrix, aliases, defaults, accepted values, and
placements are owned by
docs/CLI_V1_CONTRACT.md.
pcapraven analyze --format csv is unsupported and rejected with exit code
2. pcapraven --help, pcapraven help, pcapraven --version, and
their frozen aliases remain functional.
2. Argument and Limits Validation
- Local capture paths only. No URLs, S3, cloud storage, stdin, glob expansion, or live capture.
- Configured limits (
--max-records, --max-flows, --max-flow-instances, --tcp-idle-timeout,
--udp-idle-timeout) are validated against library builder safety bounds.
- Parser storage types are
u64 for --max-records, usize for
--max-flows, --max-flow-instances, and --max-observations, and
u32 for both idle timeouts. Preserve the downstream conversion and
architecture-dependent usize behavior documented by the canonical
contract.
- Findings/analyze filters are
--min-severity, --min-confidence,
--detector, and --mitre. Canonical values are documented there;
undocumented domain-parser tolerance is not a public compatibility promise.
- Invalid configuration or usage errors immediately exit with code 2.
3. Exit Code Contract
0: Successful complete command execution.1: Fatal input, I/O, or analysis failure before any useful result.2: Usage or configuration error (e.g. invalid arguments, malformed limits).3: Useful result produced, but analysis/validation was partial (e.g. flow exclusions,
degraded temporal metrics, capture recovery/partial termination).
4. Output Stream Separation
stdout: Strictly the requested report, help, or version result. No
diagnostics, warnings, progress, or debug messages.stderr: Strictly diagnostics, warnings, and fatal error messages.
Usage text is also on stderr for parser/configuration failures. No report
rows or report payload is written there.- Zero ANSI escape sequences / color codes.
5. Diagnostic Bounding and Quiet Mode
- Stderr nonfatal diagnostic output is bounded by a strict display budget (default 100 lines).
- When the budget is exceeded, a single summary line reports suppressed messages unless quiet.
--quiet suppresses nonfatal stderr diagnostics and suppression summaries completely,
while preserving fatal errors, exit codes, and stdout result content identically.
6. Streaming Pipeline & Bounded Memory Policy
- Capture records are streamed incrementally via
CaptureReader::next_record().
- Never bulk-retain raw
CaptureRecord streams, unbounded packet payloads, or unbounded NormalizedPacket instances.
- When evaluating detectors, finding correlation, or generating unified analysis reports, finite bounded vectors of canonical
FlowRecords and ProtocolObservations may be retained subject to configured capacity limits (--max-flows, --max-flow-instances, --max-observations).
- Capture payload bytes are released immediately upon normalization.
7. Truthful Finalization
- Clean end-of-input finalizes active flows with
FlowEndReason::EndOfInput.
- Early/abnormal termination with useful flow state finalizes active flows with
FlowEndReason::AnalysisStopped via reconstructor.finish_partial().
- Abnormal termination must never masquerade as clean
EndOfInput.
8. Factual Flow Presentation
- Flow table presents transport-level facts only (numeric ports, canonical endpoints A/B).
- Never guess client/server roles, application protocol names (e.g. port 443 as HTTPS), or
threat classifications (no "suspicious", "C2", or severity/confidence columns).
- Durations and temporal metrics are displayed exactly without floating-point conversion.
9. Output Files and Input Sources
--output/-o uses exclusive create-new semantics. Never overwrite an
existing file, create parent directories, or add a force option.- Existing-file collisions are exit 2; creation and render/flush failures are
exit 1. A newly created file is removed when a later render or flush fails
where removal is possible. Successful file output leaves stdout empty.
CAPTURE is a local filesystem path. Do not add implicit stdin, URL,
cloud-object, live-interface, or glob input.- Preserve the standard
-- option terminator behavior for positional
capture paths.
10. Frozen Compatibility Policy
- After Phase 21, removing or renaming a command or public option, removing a
short alias, changing option scope, canonical values, defaults, format
compatibility, exit categories, stream placement, quiet semantics, output
collision behavior, requiredness, or local-only input is an incompatible
change.
- A release-blocking security correction that requires such a break must
explicitly reopen the Phase 21 decision with user approval. Do not hide it
in a later phase.
- Consult
docs/CLI_V1_CONTRACT.md for the authoritative exact wording and
compatibility list.
11. Contract Verification Procedure
- Read
docs/CLI_V1_CONTRACT.md before changing CLI declarations or
orchestration.
- Generate candidate help, usage, and error output outside the canonical
snapshot tree; inspect it byte-for-byte before accepting snapshots.
- Keep CLI surface snapshots in
tests/cli_contract/ and report payload
goldens in tests/golden/. Do not substitute one for the other.
- Maintain
crates/pcapraven-cli/tests/contract.rs for the frozen surface,
including help/version, scope, aliases, placement, format matrix, defaults,
exit states, streams, quiet mode, diagnostics, and output files.
- Run the workspace architecture inventory, formatting, lint, locked tests,
schema contract, unchanged report goldens, documentation, fixture,
robustness, security/supply-chain, and cross-platform checks required by
phase-validation.
- If production CLI source changes, apply the conditional Phase 18
performance rerun requirement before acceptance.
