Quick Start

Step 1: Install Complyctl#

See INSTALLATION.md.

Step 2: Install A Provider#

Scanning providers are standalone executables that integrate complyctl with policy engines. At least one provider must be installed before complyctl scan can run.

Available Providers#

Pre-built Linux binaries are available from the complytime-providers releases page. To build from source, see the complytime-providers README. Provider binaries go in ~/.local/share/complytime/providers/.

See the Provider Guide for authoring new providers.

Install Provider Prerequisites#

Each provider requires external tools on PATH. Install the prerequisites for the provider(s) you plan to use.

Ampel:

go install github.com/carabiner-dev/snappy@v0.2.4
go install github.com/carabiner-dev/ampel/cmd/ampel@v1.3.1

OPA:

go install github.com/open-policy-agent/conftest@v0.68.2

git is also required and is typically already installed.

OpenSCAP (Fedora / RHEL / CentOS):

sudo dnf install openscap-scanner scap-security-guide

Verify The Installation#

complyctl doctor

doctor checks whether provider binaries are discovered and whether each provider’s prerequisites are met. It also reports complypack cache health: total disk usage, orphaned versions (on disk but not tracked in state.json), and untracked versions (no state.json exists), with a suggestion to run complyctl get to rebuild state. You can also list discovered providers directly:

complyctl providers

Step 3: Create Workspace Config#

Create complytime.yaml in your working directory. This is the runtime configuration — it declares policies, targets, and variables.

policies:
  - url: <oci-reference>
    id: <short-alias>
complypacks:  # optional — provider-specific content bundles
  - url: <oci-reference>
    id: <short-alias>

variables:
  key: value

targets:
  - id: <target-id>
    policies:
      - <policy-id>
    variables:
      key: value

Variable expansion: Only targets[].variables supports ${VAR} environment variable substitution. Use this for secrets and per-target credentials. Top-level variables are workspace constants passed to providers as-is — ${...} references there are not expanded.

Example: Ampel Branch Protection#

policies:
  - url: quay.io/complytime/policies-ampel-branch-protection:latest
    id: ampel-bp

targets:
  - id: my-repo
    policies:
      - ampel-bp
    variables:
      url: https://github.com/myorg/myrepo
      specs: builtin:github/branch-rules.yaml

See the ampel provider configuration for all target variables.

Example: Cis Fedora L1 (openscap)#

policies:
  - url: quay.io/complytime/policies-cis-fedora-l1-workstation:latest
    id: cis-fedora-l1

targets:
  - id: my-system
    policies:
      - cis-fedora-l1
    variables:
      profile: xccdf_org.ssgproject.content_profile_cis_workstation_l1

Or use interactive setup:

complyctl init

init prompts for policy URLs, IDs, and targets when no complytime.yaml exists.

Available policy bundles are listed in the complytime-policies usage guide.

Step 4: Fetch Policies And Complypacks#

complyctl get

Downloads Gemara policies from the OCI registry into the local cache (~/.cache/complytime/policies/). If complypacks: entries are configured in complytime.yaml, their artifacts are also fetched into ~/.cache/complytime/complypacks/. Incremental — only fetches new or modified content.

Complypack Cache Versioning#

By default, complyctl retains one complypack version per evaluator-id. When you switch versions in complytime.yaml (e.g., from :v2.0.0 to :v1.0.0), complyctl checks the local cache first and serves the previously cached version without a network fetch. This avoids re-downloads when switching between known versions.

To retain multiple versions simultaneously, set the COMPLYTIME_CACHE_VERSIONS environment variable:

export COMPLYTIME_CACHE_VERSIONS=3
complyctl get

When a verifier is configured in complytime.yaml, local cache hits are re-verified via the registry API before being accepted.

Step 5: Verify Cache#

complyctl list

Displays cached policies and their versions.

Step 6: Generate#

complyctl generate --policy-id ampel-bp

Resolves the policy dependency graph, extracts assessment configurations, and dispatches to the matching provider via Generate RPC.

Step 7: Scan#

Scan all targets for a policy:

## Evaluationlog (default)
complyctl scan --policy-id ampel-bp

## Markdown Report
complyctl scan --policy-id ampel-bp --format pretty

## OSCAL Assessment-results
complyctl scan --policy-id ampel-bp --format oscal

## Sarif
complyctl scan --policy-id ampel-bp --format sarif

Or scan a single target (policy is inferred when the target has exactly one):

complyctl scan my-repo

complyctl scan automatically calls generate if artifacts are missing or the policy digest has changed.

Output written to ./.complytime/scan/.

Exit codes: scan exits 0 on completion regardless of whether controls passed or failed — policy findings are data, not errors. The command exits non-zero only for operational errors (provider failures, bad configuration, or zero requirements assessed). To gate a pipeline on compliance results, parse the --format output (SARIF, OSCAL) with your policy engine.

Authentication#

OCI registry: complyctl uses Docker credential helpers via oras-credentials-go. No custom configuration needed — if docker login works, complyctl get works.

Supported sources:

• ~/.docker/config.json (credHelpers, credsStore, inline auths)
• Credential helpers: docker-credential-desktop, docker-credential-gcloud, docker-credential-ecr-login, etc.

GitHub / GitLab API (ampel provider): Set the appropriate token before scanning:

export GITHUB_TOKEN=ghp_your_token_here   # GitHub
export GITLAB_TOKEN=glpat-your_token_here  # GitLab

Per-repository tokens can also be configured via the access_token target variable. See the ampel provider configuration for details.