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. It can start runs with chainctl checks run, which use your allowance, but can’t read any run, so don’t use chainctl checks run there. 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. To use the name, you also need a role that can see the organization, such as viewer. With sandbox.user alone, pass the organization’s ID. 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. During the beta, use one of the following forms:

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.

The commands also accept a directory, which stands for the commit checked out there, or a full commit SHA. During the beta, these never find your repositories’ runs, so the commands report that the platform created no run, even when checks ran. Without a REF, the commands use the current directory, so pass a pull request or a run ID instead. Refer to chainctl checks status reports no platform verdict.

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 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 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 the runs you started with chainctl checks run, newest first. During the beta, it doesn’t list pull request runs or runs after merging.

chainctl checks list [--repo REPO] [--outcome OUTCOME] [--limit N]

For example:

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

With -o json, the command prints a list with one object for each run, with its run, create_time, repository, revision, phase, and outcome.

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

During the beta, REF must be a pull request. The command can’t rerun runs after merging or runs you started with chainctl checks run. To run checks after merging again, push or merge a new commit to your default branch. To repeat a run you started with chainctl checks run, run that command again.

For example:

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

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

chainctl checks cancel

Cancels a run you started with chainctl checks run, stopping its checks that are queued or running. You can’t cancel a run that has finished.

chainctl checks cancel RUN

RUN is the run’s ID, or the start of it. During the beta, you can’t cancel pull request runs or runs after merging with chainctl. A new push to a pull request cancels the run for the previous push.

For example:

chainctl checks cancel $RUN_ID --parent $ORGANIZATION

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.

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. An owner of the organization runs it once. The chainctl develop init command also asks you to accept these terms, as described in Get started with Chainguard Checks.

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.