Commands

Migration from older docs

Use the current command names:

certyn verify            -> certyn run
certyn ci run            -> certyn run
certyn ci status         -> certyn run status
certyn ci wait           -> certyn run wait
certyn ci cancel         -> certyn run cancel
certyn ci list           -> certyn run list
certyn testcases ...     -> certyn tests ...
certyn env ...           -> certyn environments ...
certyn tickets ...       -> certyn issues ...

Core workflow

certyn init --profile dev --use-api-key --project my-app --environment staging
certyn login
certyn whoami
certyn doctor
certyn ask --project my-app "What should I check before changing checkout?"
certyn run smoke --project my-app --environment staging
certyn diagnose --project my-app <execution-id>

Run validation

run replaces both the old verify flow and the old ci run flow. It waits for the run result by default and exits non-zero when the quality gate fails.

Use exactly one target:

• --url for preview mode against a public preview URL
• --environment for an existing Certyn environment

Examples:

certyn run smoke --project my-app --environment staging
certyn run regression --project my-app --environment staging --timeout 30m
certyn run smoke --project my-app --url https://preview.example.com
certyn run smoke --project my-app --url https://preview.example.com --keep-env
certyn run list --project my-app --take 50 --skip 0
certyn run status <run-id>
certyn run wait <run-id> --timeout 30m
certyn run cancel <run-id> --reason "deployment aborted"

When a run fails, the CLI collects compact execution diagnostics by default.

Codex / Claude Code flow example:

certyn run smoke --project my-app --url https://<your-ngrok>.ngrok-free.app
certyn ask --project my-app "Why did the smoke run fail?"
certyn diagnose --project my-app <execution-id>

Ask Certyn (advisor mode)

ask is the safe single-turn advisor command. It supports project-aware tool use, plus optional extra context.

certyn ask --project my-app "Why did checkout fail after login?"
certyn ask "What should I check next?" --context "run failed with network_401 on /api/checkout"
certyn ask --project my-app --max-tool-iterations 10 --max-output-tokens 4096 "What test cases do I have?"

Diagnose executions

Use the top-level diagnose shortcut or the executions diagnose subcommand.

certyn diagnose --project my-app <execution-id>
certyn executions diagnose --project my-app <execution-id>
certyn executions conversation --project my-app <execution-id>

Tests

certyn tests list --project my-app --tag smoke --quarantined false
certyn tests get --project my-app <testcase-id>
certyn tests overview --project my-app
certyn tests report --project my-app <testcase-id>
certyn tests flakiness --project my-app <testcase-id>
certyn tests flaky --project my-app --threshold 0.20
certyn tests run --project my-app <testcase-id>
certyn tests run-many --project my-app --id <testcase-id> --id <testcase-id>

Tests (operator workflows)

certyn tests create --project my-app --name "Checkout" --instructions "Run checkout flow" --tag smoke
certyn tests update --project my-app <testcase-id> --needs-review --min-env-version 2026.02.22
certyn tests tags set --project my-app <testcase-id> --tag smoke --tag checkout
certyn tests delete --project my-app <testcase-id> --yes

Issues

issues is canonical. Older tickets examples should be migrated to issues.

certyn issues list --project my-app --activity attention --severity major --status open
certyn issues get --project my-app <issue-id>
certyn issues overview --project my-app --environment staging
certyn issues retest --project my-app <issue-id>

Issues (operator workflows)

certyn issues create --project my-app --title "Checkout button broken" --type bug --severity major
certyn issues update --project my-app <issue-id> --type bug --severity major --label checkout
certyn issues labels set --project my-app <issue-id> --label checkout --label ui
certyn issues attach --project my-app <issue-id> --kind screenshot --file ./shot.png
certyn issues verify --project my-app <issue-id> --decision passed --summary "Verified in staging"
certyn issues link-test --project my-app <issue-id> --testcase <testcase-id> --priority major

Executions

certyn executions list --project my-app --status queued,running,completed
certyn executions get --project my-app <execution-id>
certyn executions diagnose --project my-app <execution-id>
certyn executions conversation --project my-app <execution-id>
certyn executions for-issue --project my-app <issue-id>
certyn executions artifacts --project my-app <execution-id>
certyn executions notes --project my-app <execution-id>
certyn executions testcases --project my-app <execution-id>

Execution controls

certyn executions retry --project my-app <execution-id>
certyn executions stop --project my-app <execution-id>

Execution control commands require API keys with platform:manage scope.

Self-hosted runners

certyn runners pools list
certyn runners pools create --name team-pool --min-runners 1 --max-runners 5
certyn runners tokens create --pool <pool-id> --mode single_use
certyn runners list
certyn runners drain <runner-id>
certyn runners resume <runner-id>

Projects and environments

certyn projects list
certyn projects create --name "My App" --slug my-app
certyn environments list --project my-app
certyn environments create --project my-app --key staging --label "Staging" --base-url https://staging.example.com --version 2026.02.22
certyn environments update --project my-app production --base-url https://app.example.com --version 2026.02.23

environments is the canonical command group. Older env examples should be migrated.

Environment variables

certyn environments vars list --project my-app --environment staging
certyn environments vars create --project my-app --environment staging --name API_BASE --value https://api.staging.example.com
certyn environments vars update --project my-app --environment staging --var API_BASE --name API_BASE --value https://api2.staging.example.com
certyn environments vars delete --project my-app --environment staging --var API_BASE --yes

Observations

certyn observations list --project my-app
certyn observations get --project my-app <observation-id>
certyn observations search --project my-app "checkout latency spike"
certyn observations create --project my-app --title "Intermittent coupon API timeout"

JSON output

Use --json for structured output:

certyn run status <run-id> --json
certyn projects list --json
certyn environments vars list --project my-app --environment staging --json
certyn issues list --project my-app --activity attention --json
certyn tests overview --project my-app --json
certyn executions get --project my-app <execution-id> --json
certyn diagnose --project my-app <execution-id> --json

Config project mapping

# validates slug and stores local slug -> id mapping
certyn config set --profile dev --project my-app

# optional manual mapping tools
certyn config projects map --slug my-app --id <project-id>
certyn config projects get --slug my-app
certyn config projects list
certyn config projects unmap --slug my-app

GitHub outputs

When GITHUB_OUTPUT exists, run, run status, and run wait write:

• run_id
• status_url
• app_url
• state
• conclusion
• total
• passed
• failed
• blocked
• pending
• aborted

Exit codes

Code	Meaning
0	success and gate passed
1	gate failed or run cancelled
2	usage/validation/config error
3	auth/permission error
4	not found
5	timeout
130	interrupted