The commands below are provisional. Their shape is stable; the exact names may change.
The CLI is a thin client over the platform API. Anything it can do, an HTTP client can do — the CLI exists because typing a clause id into a JSON payload is not a good way to reject a clause.
Installing
npm install -g @trigger-trial/cli
trigger-trial auth login # opens a browser for the GitHub OAuth flow
Drafting
# Draft a specification from a request file or stdin
trigger-trial draft new --request ./request.md --project orders-api
# Draft only the interface contract
trigger-trial draft new --request ./request.md --project orders-api --format openapi
# Show the current draft without committing anything
trigger-trial draft show orders-api
# Draft the difference between what is approved and what exists
trigger-trial draft diff orders-api
draft new writes a draft to the platform. It does not touch your repository — nothing reaches Git until a clause is approved.
Reviewing
# List clauses awaiting a decision
trigger-trial review list --project orders-api --status in_review
# Show one clause in full
trigger-trial review show orders-api --clause refund-window-closed
# Approve a clause
trigger-trial review approve orders-api --clause refund-window-closed
# Reject a clause with a reason — the reason is retained and shapes the regeneration
trigger-trial review reject orders-api --clause refund-window-closed \
--reason "The window is 30 days for monthly plans, 7 for annual. Use the plan's own window."
# Defer a clause without blocking the build
trigger-trial review defer orders-api --clause refund-window-closed --note "awaiting payments team"
Rejections are scoped: only the named clause regenerates.
Building
# Build the current approved snapshot
trigger-trial build run --project orders-api
# Re-run a previous build from the same snapshot
trigger-trial build rerun orders-api --build bld_7f2a91
# Watch the build log
trigger-trial build watch orders-api --build bld_7f2a91
# Fetch a log slice by byte offset — this is what the UI does
trigger-trial build logs orders-api --build bld_7f2a91 --offset 0
Verification results
# Per-clause results for the latest build
trigger-trial verify results --project orders-api
# Only the clauses that are not fully verified
trigger-trial verify gaps --project orders-api
# The assertion-strength distribution
trigger-trial verify strength --project orders-api
# The defect-attribution breakdown
trigger-trial verify attribution --project orders-api
verify gaps and verify strength are the two worth putting in CI. They answer "what is not actually covered" and "how much of the coverage is real" — the questions a coverage percentage hides.
Trial environments
# Provision an environment from the latest successful build
trigger-trial env create --project orders-api
# List environments, including their state and region
trigger-trial env list --project orders-api
# The credentials and URL for a running environment
trigger-trial env credentials orders-api --env env_2c81d4
# Tear one down
trigger-trial env destroy --project orders-api --env env_2c81d4
Projects and style
# The project's accumulated style guide, derived from rejection reasons
trigger-trial style show orders-api
# Pin the model version for a project
trigger-trial config set --project orders-api model.version claude-sonnet-4-6
# Where a project is deployed
trigger-trial config set --project orders-api env.region eu-west-1
Output format
Every command supports --format json for machine-readable output, and --quiet for scripts. Exit codes are 0 on success and non-zero on failure, so the commands compose in a shell pipeline.
# Fail a pipeline when any clause is unverified
if [ -n "$(trigger-trial verify gaps --project orders-api --format json)" ]; then
echo "unverified clauses remain" >&2
exit 1
fi
Authentication
The CLI stores a refresh token in your operating system’s keychain, never in a config file. Tokens are scoped to your account and revocable from the web interface at any time.
If your environment has no keychain — a container, for example — set TRIGGER_TRIAL_TOKEN explicitly and the CLI will use it. That is the only supported way to run it unattended, and it means the token has to be handled like one.