Output channels (stdout / stderr) — contract

This document defines the rules every Foundry CLI command (forge, cast, anvil, chisel, script, verify) must follow when writing to standard output and standard error.

Status: The macros, helpers, and routing primitives described here are implemented. The per-command stdout table at the bottom is the target contract that downstream migration PRs will bring each command into compliance with; it does not yet describe today's behavior for every command.

The contract

stdout is the command's primary result and nothing else. In text mode it is one canonical value (or one record per line, tab-separated for multi-column output). In --json mode it is a single JSON document.

stderr is every other byte the command emits: warnings, errors, progress indicators, status prose, prompts, banners, ABI dumps, verification chatter.

Corollaries

• --json only changes stdout's format, never its channel cleanliness.
• --quiet suppresses stderr diagnostics and progress. The target contract is that it never alters stdout content; today sh_print!/sh_println! are still suppressed by --quiet and that bypass will be flipped on once the major prose stdout call sites in forge/script have been migrated to sh_status!. sh_err! is the documented exception: fatal errors are always emitted on stderr.
• -vvv adds stderr verbosity. It must never alter stdout content.
• A command that has no primary result (e.g. forge install) writes nothing to stdout by default.
• Prompts are diagnostics: write the question to stderr, read the answer from stdin.

The acceptance criterion this enables: an agent or shell script can run any command, discard stderr, and trust that stdout contains only the documented machine-readable result.

forge create … 2>/dev/null              # → contract address only
forge test --json 2>/dev/null | jq …    # → valid JSON, always
cast call … 2>/dev/null | xargs …       # → return value only

How to write code that follows the contract

Use the sh_* macros in [foundry_common::io]; do not call println! / eprintln! directly. A workspace-wide clippy disallowed-macros lint (see clippy.toml) forbids the four std::print* / std::eprint* macros everywhere; the sh_* macros expand to write! calls on the global Shell, so they are not affected by the lint.

The compilation reporter in foundry_common::compile writes its spinner to stderr in TTY mode (see SpinnerReporter). The non-TTY fallback still writes to stdout today; flipping it to stderr will shift many existing snapshot tests and is part of the per-command migration backlog. Calling sh_progress! directly is also acceptable for one-off progress lines.

Decision rule for any sh_println! call site

For each sh_println! call you write or review, ask:

1. Is this the canonical primary result of the command?
   • Yes → keep sh_println! (stdout).
   • No → use sh_status!, sh_warn!, sh_err!, or sh_eprintln! (stderr).
2. Does this line mix labels with data (e.g. "Deployer: 0x…")?
   • The label is prose → move the whole line to sh_status! (stderr).
   • The data alone belongs on stdout → emit just the value (sh_println!).
   • In --json mode, both belong inside the single JSON document on stdout.

Per-command stdout contract (target)

This table is the target contract that migration PRs will bring each command into compliance with. It is the source of truth for what each command's stdout will contain after migration, not necessarily what it contains today. Each row's status is one of:

• migrated — current behavior matches this contract.
• todo — current behavior does not match yet; a follow-up PR is needed.

cast

forge

anvil, chisel, script

Commands not listed here have not been classified yet — please open an issue or PR before relying on their stdout format.

References

• Macros: crates/common/src/io/macros.rs
• Shell wrapper: crates/common/src/io/shell.rs
• Spinner / progress: crates/common/src/term.rs
• Compilation reporter: crates/common/src/compile.rs
• Lint configuration: clippy.toml