Start Building for Free

Use the CircleCI CLI for config and policy development

2 months ago1 min read
Server v4.x
On This Page
  • Develop configs
  • Develop policies
  • Get policy decision audit logs
  • Input
  • Output

Develop configs

Policies for CircleCI configs detect violations and stop builds that do not comply with your organization’s policies. However, this raises an issue for local development of .circleci/config.yml files. Modifications to your config.yml can cause your pipeline to be blocked. This slows down development time and can be frustrating.

To mitigate this, you can run your config.yml against your organization’s policies locally, outside of your CI pipelines, using the CircleCI CLI. You can get immediate feedback on config compliance.

The following command requests the specified config input be judged against the organization’s policies. The command returns a CircleCI decision containing the status, and any violations that may have occurred.

Example decision command:

circleci policy decide --owner-id $ORG_ID --input $PATH_TO_CONFIG

Example CircleCI decision:

    "status": "HARD_FAIL",
    "hard_failures": [
            "rule": "custom_rule",
            "reason": "custom failure message"
    "soft_failures": [
            "rule": "other_rule",
            "reason": "other failure message"

Develop policies

The CLI provides a language-agnostic way of evaluating local policies against arbitrary config inputs. This is the recommended way of developing and testing policies. It is similar to the previous command except that it provides a path to the local policies directory.

The policy files (*.rego) present in the given policy directory (searched recursively) will form the policy bundle.

circleci policy decide --input $PATH_TO_CONFIG $PATH_TO_POLICY_DIR

Policies that use data.meta…​ values like vcs.branch or project_id should also provide a JSON file mocking those values with --metafile $PATH_TO_JSON

It is recommended that you build a test suite of policy/config combinations and run them locally, or in CI, before pushing them to your organization’s active policies.

Get policy decision audit logs

Audit logs provide documentary evidence for a policy decision being performed at a certain point of time. Audit logs include the inputs which influenced the decision, as well as the outcome of the decision.

The CLI provides a policy logs command to fetch the policy decision logs for your organization.

Following is the output of this command when run with --help flag:

circleci policy logs --help

# Returns the following:
Get policy (decision) logs

  circleci policy logs [flags]

policy logs  --owner-id 462d67f8-b232-4da4-a7de-0c86dd667d3f --after 2022/03/14 --out output.json

      --after string        filter decision logs triggered AFTER this datetime
      --before string       filter decision logs triggered BEFORE this datetime
      --branch string       filter decision logs based on branch name
      --context string      policy context (default "config")
  -h, --help                help for logs
      --out string          specify output file name
      --owner-id string     the id of the policy's owner
      --project-id string   filter decision logs based on project-id
      --status string       filter decision logs based on their status


  • The organization ID information is required, which can be provided with --owner-id flag.

  • The command accepts the following filters for logs: --after, --before, --branch, --status, and --project-id. These filters are optional. Also, any combination of filters can be used to suit your auditing needs.


  • Stdout: By default, the decision logs are printed as a list of logs to the standard output.

  • File: Output can be written to a file (instead of stdout). This can be done by providing the file path using --out flag.

Suggest an edit to this page

Make a contribution
Learn how to contribute