Quick Start

Step 1: Install Complyctl#

See INSTALLATION.md.

Step 2: Install A Provider#

Scanning providers are standalone executables placed in ~/.complytime/providers/. The filename determines the evaluator ID.

mkdir -p ~/.complytime/providers
cp bin/complyctl-provider-<name> ~/.complytime/providers/

Naming convention: complyctl-provider-<evaluator-id>. The CLI strips the prefix to derive the evaluator ID used for routing.

Available Providers#

See the Provider Guide for authoring details.

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>

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#

complyctl get

Downloads Gemara policies from the OCI registry into the local cache (~/.complytime/policies/). Incremental — only fetches new or modified content.

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/.

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.