chainctl checks command reference

The chainctl checks commands read your pull requests’ results from your terminal, start and rerun checks, summarize your checks’ history, and validate your configuration. This page lists each command’s arguments, flags, exit codes, and JSON output. For examples of the commands in use, refer to Inspect and run checks with chainctl.

During the beta, the chainctl checks and chainctl develop commands don’t appear in chainctl --help or in the chainctl reference. You can still run them, and --help on either one shows its full help.

For example, run chainctl checks status --help. You can also type chainctl ci instead of chainctl checks. If chainctl doesn’t recognize a command or flag on this page, update chainctl.

The examples on this page use acme/app#123 for a pull request. Replace $ORGANIZATION with the name of your Chainguard organization.

Commands

Access and organization

Every command on this page except validate, explain, migrate --dry, and accept-terms needs the owner or sandbox.user role in the Chainguard organization linked to the repository’s GitHub account. Without one of these roles, the commands fail with permission denied. To get a role, refer to Give teammates access.

If you created a Starter organization with chainctl develop init, you have the limited_owner role instead. That role can start runs, with chainctl checks run or with chainctl checks migrate without --dry, but it can’t read any run. Those runs use your allowance without showing you their results, so don’t use either command in a Starter organization. Read the results on GitHub instead, as described in The Details link or a chainctl checks command says you don’t have access.

The validate, explain, and migrate --dry commands read only your local checkout, so they don’t need a Chainguard account or network access.

The commands that need a role take --parent with the name or ID of your Chainguard organization. Without --parent, chainctl uses the CHAINCTL_SANDBOX_GROUP environment variable, then the default.group value in your chainctl configuration. If neither is set, it asks you to choose an organization.

Name a run

Most commands that read runs take a REF argument that names the run. Use one of the following forms:

Instead of a whole run ID, you can pass the start of it, if the run is among your organization’s 500 newest runs and no other run among them starts the same way. The IDs of runs after merging begin with post-, so pass at least a few characters after post-. If a pull request run or a run after merging is from October 16, 2026, or earlier, pass its whole ID. Only the commands that read runs accept that ID. To rerun one of these pull request runs, pass the pull request instead, and follow the rerun on GitHub, because --watch can’t follow it.

To find a pull request’s runs by commit, pass the commit at the head of its branch, even though each run tests that commit merged into the base branch. To find a run after merging, pass its commit on your default branch. If Chainguard Checks has no run for a directory’s commit or a commit SHA, the commands report no platform verdict. Refer to chainctl checks status reports no platform verdict.

The chainctl checks status -o json command prints the run’s full name in its run field. Pass that name to the other commands to keep reading the same run after someone pushes to the pull request.

Output and exit codes

To print JSON for a script or a coding agent, add -o json, which is short for --output json. Each command’s section describes its JSON.

On a terminal, commands that print your repository’s output remove escape sequences and other control characters from it. To keep them, add --raw to a command that takes it. When the output isn’t a terminal, such as when you pipe it to a file, the commands always print it as it is.

Unless a command’s section says otherwise, it exits with 0 when it succeeds and 1 when it fails.

Inspect runs

chainctl checks status

Shows a run and whether each of its checks passed.

chainctl checks status REF [--watch]

For example, to wait for a pull request’s checks to finish:

chainctl checks status acme/app#123 --watch --parent $ORGANIZATION

The output marks a failed advisory check as (advisory), and shows the label that runs each check that runs only on request. The command exits with one of the following codes:

With -o json, the command prints one object, the final one with --watch. It has the run’s run, repository, revision, pull_request, phase, and outcome, and failed, which is true when the command exits with 1. Its checks list has each check’s workflow, check, phase, and outcome, plus exit_code, advisory, and request_label when they apply. When there’s no run, the object’s status is no platform verdict.

chainctl checks failures

Shows why a run’s checks failed. For each failed check, the command shows the step that failed, with its exit code and command, and the end of the failing output, quoted from the check’s log. For Go tests that a step runs with go test -json, it quotes the failing tests. Otherwise, it quotes the programs that exited with an error, or the end of the step’s output, with a note that says which one it quoted and why. For a check with no record of why it failed, such as one that couldn’t be executed, the command shows the check’s error and a chainctl checks logs command that reads the end of its log.

chainctl checks failures REF [--check CHECK [--workflow WORKFLOW]] [--budget BYTES] [--not-run] [--raw]

For example, to see why a pull request’s checks failed:

chainctl checks failures acme/app#123 --parent $ORGANIZATION

The output starts with the run’s name, then its status and how many of its checks failed, passed, and didn’t run. The command exits with 0 when it shows failures, so use chainctl checks status to test whether a run passed.

With -o json, the command prints one object with the run’s name in target, its phase and outcome, the counts of checks that passed, failed, haven’t finished (running), or didn’t run (not_run), a failed list, and truncated, which is true when the command shortened or left out part of the output to fit --budget. Each failed check has its check, outcome, exit_code, the step that failed, and quotes from its log. Each quote has its text and the log_ranges it came from. When the log has output before the quote, the quote’s more field is the chainctl checks logs command that reads that output. A check with no record of why it failed has no quotes, and its own more field is the command that reads the end of its log. With --not-run, the object also has a not_run list.

chainctl checks logs

Prints the combined standard output and standard error of a run’s checks, followed by the errors, warnings, and notices each check reported, as described in Report errors and annotations. Without --check, the command prints every check’s log, each after a line that names the check.

chainctl checks logs REF [--check CHECK [--workflow WORKFLOW]] [--follow] [--attempt N] [--raw]
chainctl checks logs REF --check CHECK (--errors | --grep RE) [-C N] [--max N] [--offset BYTES]
chainctl checks logs REF --check CHECK --tail N
chainctl checks logs REF --check CHECK --offset BYTES [--limit-bytes N]

The --errors, --grep, --tail, --offset, and --limit-bytes flags read part of one check’s log, so they need --check, and you can’t combine them with --follow. Use only one of --errors, --grep, and --tail at a time. Each excerpt starts with the byte range it covers. If the command leaves lines out, it says so, and gives the --offset to continue from.

For example, to show a failed check’s error lines with three lines around each one:

chainctl checks logs acme/app#123 --check test --errors -C 3 --parent $ORGANIZATION

The -o json flag works only with --errors, --grep, --tail, --offset, or --limit-bytes. The command then prints one JSON object per line: one with type set to excerpt for each excerpt, with its check, attempt, offset, end_offset, and text, followed by one with type set to summary. The summary says how much the command showed, whether it left anything out, and the next_offset to continue from.

chainctl checks trace

Shows the programs that each step of a check started, with each program’s name, how long it ran, and how it exited. Chainguard Checks records program names, never their arguments. For a failed step, the output names the program that most likely failed it. This guess comes from the recorded programs, so it can be wrong, such as when a shell or build tool ignores a program’s exit code.

chainctl checks trace REF [--check CHECK [--workflow WORKFLOW]] [--failed]

For example:

chainctl checks trace acme/app#123 --check test --failed --parent $ORGANIZATION

A trace marked INCOMPLETE lost some of its records, or chainctl cut it to fit, so parts of it might be missing. With -o json, the command prints one JSON object per line for each step, with the step’s workflow, check, step number, and its tree of programs in document.

chainctl checks attempts

Lists each attempt at a check, oldest first. For each attempt, the command shows why it ran, such as an automatic retry or a rerun, how it ended, when it started, and how long it took. It also marks each attempt whose result Chainguard Checks reused from an earlier run, and names that run. After the list, the command shows each attempt’s error, if it had one, and how long the attempt spent queued, waiting for a free slot, booting its VM, setting up, and running its steps.

chainctl checks attempts REF --check CHECK [--workflow WORKFLOW]

For example:

chainctl checks attempts acme/app#123 --check test --parent $ORGANIZATION

To read one attempt’s log or events, pass its number to --attempt in chainctl checks logs or chainctl checks events. With -o json, the command prints one object with the check’s workflow_run, workflow, and check, and its attempts as the API returns them.

chainctl checks events

Prints the events that one attempt at a check recorded, in order: when its setup, each of its steps, and each program that a step started began and ended, and any diagnostics attached to them.

chainctl checks events REF --check CHECK [--workflow WORKFLOW] [--attempt N]

For example:

chainctl checks events acme/app#123 --check test --parent $ORGANIZATION

With -o json, the command prints the events as the API returns them.

chainctl checks describe

Shows where a run came from, its status, and each of its checks.

chainctl checks describe RUN [--steps] [--events]

RUN is a run ID, as described in Name a run. The command doesn’t take a pull request, so to describe a pull request’s run, pass the run field that chainctl checks status -o json prints.

For example:

chainctl checks describe $RUN_ID --events --parent $ORGANIZATION

With -o json, the command prints one object with the run, its workflow_runs, and with --events, its events, as the API returns them.

chainctl checks list

Lists your organization’s runs, newest first: pull request runs, runs after merging, and runs that anyone started with chainctl checks run. It doesn’t list pull request runs or runs after merging from October 16, 2026, or earlier.

chainctl checks list [--repo REPO] [--ref REF] [--trigger presubmit|postsubmit] [--outcome OUTCOME] [--limit N]

For example, to list the failed runs after merging on main:

chainctl checks list --repo acme/app --ref main --outcome failed --parent $ORGANIZATION

The output has one row for each run, with the columns RUN, CREATED, REPOSITORY, REF, COMMIT, PR, TRIGGER, and STATUS. The RUN column is the run’s ID. For a pull request run, COMMIT is the head of the pull request, and PR is the pull request’s URL. COMMIT shows the start of the commit’s SHA, so to name the commit in another command, use the full SHA in the revision field of the -o json output. A run started with chainctl checks run has - under both REF and PR. The STATUS column shows queued, running, or cancelling until the run finishes, then its outcome, such as passed.

With -o json, the command prints a list with one object for each run, with its run, create_time, repository, ref, revision, pull_request, trigger, phase, outcome, and cancel_requested. The command leaves out fields that have no value, such as outcome for a run that hasn’t finished.

Start and stop runs

chainctl checks run

Runs a commit’s checks in Chainguard Checks without a pull request. The commit must be pushed to GitHub, because Chainguard Checks reads its configuration from there through your organization’s link to the repository’s GitHub account. To run checks against uncommitted changes, use chainctl develop check instead, as described in Run checks in a session from your laptop.

chainctl checks run [DIR] [--check CHECK [--workflow WORKFLOW]] [--request CHECK]... [--git-remote NAME] [--base REV] [--watch]

DIR is a local checkout, the current directory by default. The command runs the commit checked out there, in the github.com repository of its origin remote.

For example, to run the test check and wait for its result:

chainctl checks run . --check test --watch --parent $ORGANIZATION

The run doesn’t report to GitHub, and it never counts as a pull request’s or commit’s result. It uses your organization’s Checks allowance like any other run. Because the run has no pull request, the command refuses a check whose when.expr condition reads the trigger, the pull request, or its labels.

The command prints the run’s name, followed by its checks. The run’s ID is the part of the name after /runs/. Pass the ID to chainctl checks status, cancel, or the other commands that read runs. With --watch, the command exits with 1 when a blocking check doesn’t pass. With -o json, it prints the run as the API returns it, or with --watch, the run’s final status in the same form as chainctl checks status -o json.

chainctl checks rerun

Reruns a pull request’s latest run after it finishes, the same way as Re-run on GitHub. Refer to Rerun checks for what reruns and how to follow the new run.

chainctl checks rerun REF [--watch]

REF is a pull request, a directory, a commit SHA, or a run ID, as described in Name a run, and it must name a pull request’s run. When you name the run by a directory, a commit SHA, or a run ID, the run must be for the same commit as the pull request’s newest run.

During the beta, the command can’t rerun checks that run after merging. If REF names a run after merging, such as a run whose ID starts with post-, the command fails with cannot rerun: ... is neither a postsubmit Run nor a pull request's. To run the checks again, push or merge a new commit to your default branch. The command also can’t rerun runs you started with chainctl checks run. To repeat one of those, run that command again.

For example:

chainctl checks rerun acme/app#123 --parent $ORGANIZATION

With --watch, the command exits with 1 when a blocking check doesn’t pass. With -o json, it prints the run whose checks it reruns, as the API returns it. With --watch and -o json, it prints the new run’s final status instead, in the same form as chainctl checks status -o json.

chainctl checks cancel

Cancels a run that hasn’t finished, stopping its checks that are queued or running. Checks that already finished keep their results. The command returns once Chainguard Checks accepts the request, before the checks stop. Canceling a run again changes nothing.

chainctl checks cancel RUN [--force]

RUN is a run ID, as described in Name a run, or the run’s full name. The command doesn’t take a pull request, so to cancel a pull request’s run, pass the run field that chainctl checks status -o json prints.

Anyone with the owner or sandbox.user role in your organization can cancel any of its runs, including runs that someone else started. The --force flag doesn’t change who can cancel a run. It only confirms that you mean to stop a run that GitHub started.

For example, to cancel a pull request’s run:

RUN=$(chainctl checks status acme/app#123 -o json --parent $ORGANIZATION | jq -r .run)
chainctl checks cancel "$RUN" --force --parent $ORGANIZATION

When you cancel a run that GitHub started, its summary check on GitHub ends with Run cancelled and doesn’t pass. To run a pull request’s checks again, push a new commit, or rerun them as described in Rerun checks. Adding a ci/run: label or editing the pull request doesn’t start a new run. To run checks after merging again, push or merge a new commit to your default branch.

To find out when Chainguard Checks cancels a pull request’s run on its own, refer to When Checks runs.

With -o json, the command prints the run as the API returns it.

Summarize check history

The stats, top, and trends commands summarize your organization’s checks across runs. For examples, refer to See check history.

The top and trends output starts with the window it read and how current its data is, because the newest attempts can take time to appear. The first time you run either command, chainctl might ask you to sign in again. Without a terminal to sign in at, such as in a script, the command fails and prints the chainctl auth login command to run first.

chainctl checks stats

Counts the outcomes of your organization’s newest runs, by repository and by check.

chainctl checks stats [--limit N]

In the output, OPEN counts runs or checks that haven’t finished, and RUNNING is the part of OPEN that’s running. FAIL% is the share of failed results among the results that passed or failed, so checks that are still running, were canceled or skipped, or couldn’t finish don’t change it. CONFIGS counts the different configurations a repository’s runs used.

With -o json, the command prints one object with the number of runs it read and a repositories list. Each repository has its name, counts, configs, and a checks list with each check’s name, counts, and median_seconds. Each counts object has total, passed, failed, errored, dependency_failed, not_instantiated, cancelled, open, and running.

chainctl checks top

Ranks your organization’s checks over a window of time.

chainctl checks top [--repo REPO] [--since DURATION | --from TIME --to TIME] [--by count|runtime|failures] [--limit N]

A check’s failure rate is the share of its attempts that failed or couldn’t finish, such as by timing out. Attempts include retries, but not attempts whose result Chainguard Checks reused from an earlier run.

With -o json, the command prints one object with the window, when the data was generated (generatedAt), the ranking (by), and a checks list. Each check has its job_ref, name, attempts, failed, errored, runtime_seconds, and failure_rate, which is null for a check with fewer than 100 attempts.

chainctl checks trends

Shows the median, 95th percentile, and 99th percentile durations of checks for each hour of a window, for the 10 checks with the most total runtime in that window. Hours with no attempts don’t appear.

chainctl checks trends [--repo REPO] [--since DURATION | --from TIME --to TIME] [--check CHECK]

With -o json, the command prints one object with the window, generatedAt, and a trends list with one object for each check and hour. Each object has the check’s job_ref, the hour, the number of attempts it measured in samples, and the median_seconds, p95_seconds, and p99_seconds durations.

Set up checks

chainctl checks validate

Finds problems in your configuration without running anything, the way Chainguard Checks reads it for a pull request, with the differences described in Validate your configuration offline. That section also shows the command’s output.

chainctl checks validate [PATH]

PATH is a repository’s root directory, a configuration file under its .chainguard/ directory, or a standalone configuration file. For a file under .chainguard/, the command validates its repository’s whole configuration. Without PATH, the command validates the repository that the current directory is in.

For example, to validate another repository’s configuration:

chainctl checks validate ../app

The command exits with 1 when the configuration has a problem that Chainguard Checks would refuse. Warnings, such as for a key that Chainguard Checks ignores, don’t change the exit code. With -o json, the command prints one object with the repository’s root, the problems that kept it from reading the configuration in diagnostics, and a workflows list. Each workflow has its workflow name, its path, its refusals and warnings, problems with needs in graph, and ok. The object’s own ok is true when the whole configuration is valid.

chainctl checks explain

Prints each check as Chainguard Checks reads it for a pull request, with its environment, trigger, steps, and resource class, without running anything.

chainctl checks explain [DIR] [--raw]

DIR is the repository’s root directory. Without it, the command reads the repository that the current directory is in.

If Chainguard Checks would refuse the configuration, the command prints each problem with its file and position, and exits with 1. With -o json, it prints the resolved configuration, or the problems when it’s refused.

chainctl checks migrate

Drafts a .chainguard/ci/migrated.yaml file from your repository’s GitHub Actions workflows that run on pull_request. Refer to Migrate from GitHub Actions to Chainguard Checks for how to review the draft.

chainctl checks migrate [PATH] [--dry]

PATH is a local clone whose origin remote is on github.com, the current directory by default. The --dry flag drafts the file and prints it, followed by a list of what the draft carried over, flagged, and ignored, without running anything.

Without --dry, the command also tests the draft by running its checks in your organization, up to six times. These runs need a role, as described in Access and organization, and use your organization’s Checks allowance like any other run. In the first run, each check that has no egress list can reach any host by name, so that the command can draft its list. Chainguard Checks still refuses connections to IP addresses, private ranges, and metadata endpoints. During the beta, use --dry to avoid these runs.

For example, to write the draft to its file:

mkdir -p .chainguard/ci
chainctl checks migrate --dry -o json | jq -r .document > .chainguard/ci/migrated.yaml

With -o json, the command prints one object with the repository, revision, the draft’s path, the number of jobs it drafted, the draft itself in document, and the ledger of what it carried over, flagged, and ignored.

chainctl checks accept-terms

Accepts the terms that Chainguard Checks is offered under for your organization: the Code Analysis Terms and the Master Service and License Agreement. Someone with the owner or limited_owner role runs it once. The chainctl develop init command also asks you to accept these terms, as described in Sign up with chainctl develop init.

chainctl checks accept-terms [--parent ORGANIZATION] [--yes]

For example:

chainctl checks accept-terms --parent $ORGANIZATION

Running the command again after the organization accepts the terms changes nothing.