Skip to main content
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
Nothing runs in your editor: no AI client, no local devtools server, no completion gate. It’s the same kind of verification your agent performs locally, packaged as a command you can run from any shell or CI pipeline. Each job appears in the console as a verification run on the project’s Verifications tab.
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 reaches 127.0.0.1:<port> on your machine without you exposing anything.
An API run may reach only the hosts it’s told about: the target, the environment’s URL and OpenAPI properties, and the hosts its secrets are bound to.

Credentials

The command authenticates with your IronBee account. Run ironbee 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:
  1. IRONBEE_ACCESS_TOKEN
  2. IRONBEE_SERVICE_OAUTH_TOKEN, else service.oauthToken in the config files
  3. the legacy IRONBEE_OAUTH_TOKEN, else collector.oauthToken in the config files
  4. IRONBEE_API_KEY
  5. IRONBEE_SERVICE_API_KEY, else service.apiKey in the config files
  6. collector.apiKey in the config files
So on a machine where you ran 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:
The value is masked from all CLI output the moment it’s parsed, and registered with ::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, --url must fall inside those domains, and a --port target is refused because a tunnel has no domain.
When the API refuses a job over the environment, the error line ends with how to recover: 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 its workspace/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 --pr other 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.
A bound run on a repository the IronBee GitHub App covers, on a gitlab.com project whose group is connected, or on a bitbucket.org repository whose workspace is connected, reports its result there: a check, a build status, or a pipeline status where IronBee writes one (Merges), on the commit, and on an open pull or merge request an inline comment on each finding in the diff and a summary comment. See What appears on the pull request. To keep the run off the repository, pass --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-wait runs out (default 60s), the command exits 1 with the last probe error.
Once the job is created, the CLI prints every status change (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 prints created 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, fixes and reason lists
  • a credits line: the credits the job used and what your team has left this month, not charged, or unlimited. When CI is 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, or no verdict with the job’s status
When your team is out of credits, the job isn’t created: the command says when the credits reset and how to raise the allowance, and exits 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:
  • status is one of queued, starting, running, succeeded, failed or cancelled.
  • result.status is pass, fail or not_applicable.
  • A failing result carries findings, the structured problems its issues and fixes are derived from. Each has an id, a title, a severity (critical, high, medium or low), a kind (correctness, security or editorial), and when, then and proof. It may also carry impact, where (the path and line of the problem), fix (a note, and optionally code with replaceLines, the lines that code replaces, such as 42-44) and refs, the other places the finding relies on.
  • result.head is the commit the run checked out, or null when the run had no repository.
  • publication says whether IronBee publishes the run on the repository: its provider (github, gitlab or bitbucket) and its status (pending, succeeded or failed). It’s null when the run isn’t published there.
  • credits.estimated is the most the job can use, and credits.charged what it used once it ended. Each is null until it’s known.
  • The body also carries the resolved environment, the project, the target type in input.type, the trigger, and the created, started and ended timestamps.
  • The result may carry refused: true with a reasonCode when the run declined or narrowed part of the request. A refused run can still be succeeded, so a caller should check it.
  • The job may carry an error: { type, message }.
  • With --no-wait --json, the output also includes the create-time notices.
A failure that produced no job prints a machine-readable error envelope instead. Tell the two apart by the presence of id:
error.code is the API’s own error code, and the field to branch on. Codes worth handling include: 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.