Command-line interface

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.

Next