ironbee verify starts a verification job through the IronBee API. A cloud agent verifies your application and returns a verdict:
- the target: a deployed URL, or a local app reached through a reverse tunnel
- how it verifies: in a browser for a web app, by calling it for an API
Earlier CLI versions used
ironbee verify [session-id] for a local dry-run of a session’s verdict checks. That command is now ironbee verdict. ironbee verify is exclusively the cloud verification job runner.Targets
Both take the same flags. The target is exactly one of:
--url <url>: a publicly reachable deployment. The cloud agent reaches it directly.--port <number>: a local application. The CLI holds a reverse tunnel open for the duration of the run, so the cloud agent reaches127.0.0.1:<port>on your machine without you exposing anything.
Credentials
The command authenticates with your IronBee account. Runironbee login once, or supply a credential from the environment, which is the way to do it in CI:
An OAuth token from any source wins over an API key from any source. The command takes the first credential it finds, in this order:
IRONBEE_ACCESS_TOKENIRONBEE_SERVICE_OAUTH_TOKEN, elseservice.oauthTokenin the config files- the legacy
IRONBEE_OAUTH_TOKEN, elsecollector.oauthTokenin the config files IRONBEE_API_KEYIRONBEE_SERVICE_API_KEY, elseservice.apiKeyin the config filescollector.apiKeyin the config files
ironbee login, the stored OAuth token wins over an IRONBEE_API_KEY or IRONBEE_SERVICE_API_KEY you export. Export IRONBEE_ACCESS_TOKEN or IRONBEE_SERVICE_OAUTH_TOKEN to override it.
An OAuth token acts with your role in the account. Starting or cancelling a job needs the owner, admin or member role: the API refuses a billing admin’s token with FORBIDDEN. The account API key isn’t tied to a role.
ironbee verify reads the global, project and local config files. It doesn’t read the repository’s personal file, so a credential kept only there doesn’t reach it. With no credential at all, the command fails with no IronBee credential. The credential is never a CLI argument, so it can’t leak through the process table.
Flags
Target flags
--header and --secret-header apply to --url only: a tunnel target’s traffic passes no layer that could apply them.
Common flags
--prompt and --prompt-file are alternatives. --no-wait can’t be combined with --port: the run reaches the application only while the command is holding the tunnel open.
Secret headers for protected deployments
A preview deployment behind deployment protection, such as Vercel’s, needs a header to reach it. Pass it with--secret-header so the value is treated as a secret end to end:
::add-mask:: on GitHub Actions runners. It’s sent in a dedicated secretHeaders field that the service encrypts and never reads back. Plain --header values get none of that treatment, so use them only for non-sensitive headers.
To store a bypass for every run instead of passing it each time, add it as a project secret.
Environments
--environment <name> names the deployment the run is against, such as staging or preview. The run uses that environment’s variables and secrets on top of the project-wide ones. Without it, the run uses the project-wide ones only.
- A name the project hasn’t seen yet is created by the job.
- When the environment has Domain properties,
--urlmust fall inside those domains, and a--porttarget is refused because a tunnel has no domain.
See Environments.
The same goes for an archived project:
PROJECT_ARCHIVED ends with a hint to unarchive the project in the console, or to enable the repository again.
Binding the run to your repository
By default the run is bound to your repository and current commit, so the verdict lands next to the right code in the console. Fine-tune or opt out:
The binding attaches only when it would actually work:
- The remote must be on GitHub, gitlab.com or bitbucket.org. A gitlab.com project is bound by its full path, such as
acme/platform/backend, through its group connected in the IronBee console. A bitbucket.org repository is bound by itsworkspace/repo_slug, through its workspace connected in the console. A self-managed GitLab server and Bitbucket Data Center or Server aren’t supported. - A commit derived from local HEAD must be reachable from a remote-tracking branch. An unpushed HEAD produces a warning, and the run proceeds unbound rather than pointing at code the service can’t read. An explicit
--commit, or the CI job’s commit, is taken at face value. - A dirty working tree only warns. The run stays bound to the committed SHA, which it reads from GitHub, GitLab or Bitbucket, so what the agent reads and what’s on your disk may differ.
- On Bitbucket, the run also names the branch, so its build status reaches the pull request: the Pipelines step’s
BITBUCKET_BRANCH, or your branch’s name on the remote when that remote branch holds the commit. An explicit--commit, or a--prother than the step’s own, names no branch. A name over 200 characters, or with characters other than letters, digits,.,_,/and-, isn’t sent, and the CLI warns that the run’s status may not reach its pull request.
--no-repo.
In GitHub Actions the binding is automatic: GITHUB_REPOSITORY, GITHUB_SHA and GITHUB_REF fill in the repo, commit and pull request. The job is declared with a github_actions trigger, so the console shows it as GitHub Actions. If the job fails with a repository checkout error, grant the IronBee GitHub App access to the repository (on GitLab, connect the project’s group in the console; on Bitbucket, its workspace), or re-run with --no-repo.
In a gitlab.com CI job of the same project, the binding is automatic too, even on a detached checkout. The run binds to the merge request in CI_MERGE_REQUEST_IID when it’s that project’s, else to the commit in CI_COMMIT_SHA. The job is declared with a gitlab_ci trigger, so the console shows it as GitLab CI. A gitlab.com remote is never bound through GITHUB_REPOSITORY. See Environment variables.
In a Bitbucket Pipelines step of the same repository, the binding is automatic too. The run binds to the pull request in BITBUCKET_PR_ID, else to the commit in BITBUCKET_COMMIT (a short one is expanded with git), and names the step’s BITBUCKET_BRANCH. The job is declared with a bitbucket_pipelines trigger, so the console shows it as Bitbucket Pipelines. A bitbucket.org remote is never bound through GITHUB_REPOSITORY.
A CI trigger has to match the repository’s host: GitHub Actions goes with a GitHub repository, GitLab CI with a gitlab.com project, and Bitbucket Pipelines with a bitbucket.org repository. The API refuses a job bound to, or claiming, a repository of another host. To verify across hosts, pass --no-repo and --project <name>.
Which project. Without --project, the project name comes from your repository. That’s the origin remote’s repository name, else the first remote’s, else the repository folder’s name. A gitlab.com project is named by the path after its group, with / as -. A checkout of a github.com repository, a gitlab.com project or a bitbucket.org repository whose name matches reports to that repository’s own project. For a job, that’s the repository the run is bound to, the remote your branch is pushed to: a branch pushed to a fork, or to another host, reports to that repository’s project when its name matches, and claims none otherwise. In GitHub Actions, GitLab CI or Bitbucket Pipelines, the job reports to the GitHub, GitLab or Bitbucket project with that name. --project <name> names the project explicitly and doesn’t claim a repository’s project. See How IronBee identifies your project.
How a tunnel run starts
For a--port target, the CLI first probes the local port, before creating the job, so a doomed run is never started:
- It keeps waiting while nothing is listening, and while the port accepts and immediately hangs up (Docker publishes a container’s port before the app inside is ready).
- A server that accepts but stays silent is treated as ready (just slow), not as a failure.
- A TLS listener fails immediately: the tunnel carries plain HTTP, so serve the app over HTTP locally.
- When
--app-waitruns out (default 60s), the command exits 1 with the last probe error.
queued, starting, running, then a terminal status) while holding the tunnel. When the run finishes, the service closes the tunnel with a dedicated “run ended” signal and the command stops without reconnecting. If that signal is ever lost, the command falls back to the job’s own status polling; the verdict is the same either way. Ctrl-C requests a cancel and waits for the service to confirm; a second Ctrl-C exits immediately.
Output and exit codes
When the job is created, the CLI printscreated job <id>. With --timeout, the line also says the most credits the job can use at that timeout. Any notices from the service follow as warnings, for example when the project the job resolved to has none of the variables or secrets a same-named project holds.
A finished run prints:
- the job’s summary
- its
checks,issues,fixesandreasonlists - a
creditsline: the credits the job used and what your team has left this month,not charged, orunlimited. WhenCIis set to any non-empty value, the team’s balance is left out - a warning when the run refused or narrowed part of the request
- a final banner:
PASS,FAIL,NOT APPLICABLE, orno verdictwith the job’s status
1. See When credits run out.
That makes it CI-gate-ready:
ironbee verify run web --url … && deploy.sh.
--json
With --json, stdout carries exactly one JSON document, and all decoration goes to stderr. A run that produced a job prints the job body:
statusis one ofqueued,starting,running,succeeded,failedorcancelled.result.statusispass,failornot_applicable.- A failing result carries
findings, the structured problems itsissuesandfixesare derived from. Each has anid, atitle, aseverity(critical,high,mediumorlow), akind(correctness,securityoreditorial), andwhen,thenandproof. It may also carryimpact,where(thepathandlineof the problem),fix(anote, and optionallycodewithreplaceLines, the lines that code replaces, such as42-44) andrefs, the other places the finding relies on. result.headis the commit the run checked out, ornullwhen the run had no repository.publicationsays whether IronBee publishes the run on the repository: itsprovider(github,gitlaborbitbucket) and itsstatus(pending,succeededorfailed). It’snullwhen the run isn’t published there.credits.estimatedis the most the job can use, andcredits.chargedwhat it used once it ended. Each isnulluntil it’s known.- The body also carries the resolved
environment, the project, the target type ininput.type, the trigger, and the created, started and ended timestamps. - The result may carry
refused: truewith areasonCodewhen the run declined or narrowed part of the request. A refused run can still besucceeded, so a caller should check it. - The job may carry an
error: { type, message }. - With
--no-wait --json, the output also includes the create-timenotices.
id:
error.code is the API’s own error code, and the field to branch on. Codes worth handling include:
UNAUTHORIZEDandACCOUNT_INACTIVEPROJECT_ARCHIVEDCREDITS_EXHAUSTED(status402), whose numbers come aserror.credits. See When credits run out- the environment codes above
status and details appear only when the failure came from the API. A purely local failure, such as flag validation or a missing credential, carries only message.
On a GitHub Actions runner the CLI also writes
::add-mask:: workflow-command lines to stdout, masking the credential and any --secret-header values with the runner. A --json consumer there should parse the last JSON document rather than assume the stream is pure JSON.ironbee verify status and cancel
status accepts the same --json, --api-url and -C, --project-dir flags as run, plus --queue-wait <seconds> with --watch. As an observer it never cancels: if the queue wait elapses, it just warns that the job is still queued. For a finished job, it also prints the credits line.
What’s next?
Verification
The in-editor verification gate: cycles, modes, and the verifier sub-agent.
Authentication
OAuth tokens for interactive use, API keys for CI.
Credits
What a job costs, and how to see what your team has left.
Code review
Review your branch before you open a pull request.