Exit codes (Tier-1)

ShipGate uses numeric exit codes so CI can branch on success vs failure. This page describes implemented behavior for Tier-1 commands, not every subcommand in the CLI.

Global constants

Defined in the CLI source as ExitCode:

Code	Name	Typical meaning
0	SUCCESS	Success; SHIP where applicable
1	ISL_ERROR	NO_SHIP, verification/gate failure, or Tier-1 “failure” path
2	USAGE_ERROR	Bad flags, missing required arguments (often via Commander exitOverride)
3	INTERNAL_ERROR	Unexpected internal failure
4	WARN	Reserved for --fail-on warning style behavior where implemented

Tier-1 commands

Command	Success	Failure	Usage / CLI errors
shipgate check	0	1 (parse/type errors)	2 when Commander rejects argv
shipgate verify	0 (getVerifyExitCode → success)	1	2 for usage
shipgate gate	0 (getGateExitCode → result.exitCode, normally SHIP)	1 (NO_SHIP or gate failure)	2 if required options missing (e.g. no --impl)
shipgate next	0 (getNextGateExitCode when result.success)	1 when not successful	2 for usage
shipgate go	0 for SHIP or WARN (getGoExitCode)	1 for other verdicts	2 for usage

Important: For gate, the verdict path is almost always 0 or 1. Codes 2 and 3 apply to CLI invocation (bad args) or rare internal errors, not to a normal NO_SHIP verdict.

CI recommendations

• Treat non-zero as “block merge” unless you explicitly allow 2 for “misconfigured workflow” only.
• Prefer --format json or --ci on supported commands for stable logs.
• For Next.js golden path, use --format quiet plus --evidence-out / --summary-out so PRs always get a file-backed reason.

Related

• CLI: gate — gate-specific usage
• CLI: next — Next.js gate + evidence
• Tier-1 supported surface