@driftgard/cli

Governance-as-code CLI for Driftgard — manage control packs from your terminal and CI pipelines.

Install

npm install -g @driftgard/cli

Or run directly with npx:

npx @driftgard/cli help

Configure

export DRIFTGARD_API_KEY=dg_your_api_key
export DRIFTGARD_PROJECT_ID=proj_xxx

Commands

pull

Download the active control pack as YAML or JSON.

driftgard pull --format yaml
driftgard pull --pack ./control-packs/prod.json --format json

push

Upload a local control pack as a new version. Auto-increments the version number.

driftgard push --pack ./control-packs/prod.yaml

activate

Set a specific version as the active control pack.

driftgard activate --pack-id my_control_pack --version 3

validate

Check a control pack file for structural errors. Works offline.

driftgard validate --pack ./control-packs/prod.yaml

lint

Check for logical issues — contradictions, unreachable thresholds, dead patterns, and more. Works offline.

driftgard lint --pack ./control-packs/prod.yaml

Checks for:

• Duplicate clause IDs
• Unreachable block threshold (no single violation can trigger a block)
• Guaranteed block on any violation (threshold too low)
• Dead patterns (rules with no pattern_rules — judge-only)
• Duplicate patterns across rules
• Auto-block category with low severity (misleading label)
• Category multipliers on unused categories
• Auto-block categories with no matching rules

Exits with code 1 if errors are found. Warnings and info do not fail.

promote

Copy a control pack from one project to another. Useful for promoting from staging to production.

# Promote the active control pack
driftgard promote --from-project proj_staging --to-project proj_prod

# Promote a specific version
driftgard promote \
  --from-project proj_staging \
  --to-project proj_prod \
  --pack-id ft_au_fintech_v1 \
  --version 2

# Promote and activate immediately in the target project
driftgard promote --from-project proj_staging --to-project proj_prod --activate

The version is auto-incremented in the target project.

diff

Show a colored diff between the latest two control pack versions.

driftgard diff

benchmark

Run the benchmark suite and fail if thresholds are exceeded. CI-friendly — exits with code 1 on failure.

driftgard benchmark --max-violation-rate 0.05 --max-blocked 10

test

Run the control pack's test cases against the evaluator. Exits with code 1 if any test fails. CI-friendly.

# Run test cases from a local pack file
driftgard test --pack ./control-packs/prod.yaml

# Run test cases from the active control pack (no --pack flag)
driftgard test

Test cases are defined in the control pack's test_cases array. Each case specifies an input (prompt/response or tool call) and an expected outcome (allow or block).

Tool rules with identity

Each tool can have identity_rules — restricting which agents, roles, users, or parent agents can call it. OR logic across rules, AND logic within each rule:

tool_rules:
  rules:
    transfer_money:
      parameters:
        amount:
          type: number
          max_value: 10000
          custom_fn: "value > 0"
        to_account:
          type: string
          custom_fn: "value !== params.from_account"
      identity_rules:
        - allowed_roles: [payments_agent]
          allowed_users: [user_alice, user_bob]
        - allowed_roles: [admin_agent]
    close_account:
      parameters:
        account_id:
          type: string
          must_match: "^acc_[a-z0-9]+$"
      identity_rules:
        - allowed_roles: [admin_agent]
          allowed_agent_ids: [agent_admin_001]
          allowed_users: [user_admin]
          allowed_parent_agents: [orchestrator_main]

If no identity_rules are defined on a tool, any caller can use it. All four fields (allowed_roles, allowed_agent_ids, allowed_users, allowed_parent_agents) are optional within each rule.

Test cases with identity

Tool call test cases can include identity fields to test identity rule enforcement:

test_cases:
  - name: "Allowed transfer by payments agent"
    expected: allow
    input:
      tool_name: transfer_money
      parameters:
        amount: 500
        from_account: acc_savings
        to_account: acc_checking
      agent_role: payments_agent
      on_behalf_of: user_alice

  - name: "Blocked transfer by wrong role"
    expected: block
    input:
      tool_name: transfer_money
      parameters:
        amount: 500
        from_account: acc_savings
        to_account: acc_checking
      agent_role: support_agent

  - name: "Blocked close without full identity"
    expected: block
    input:
      tool_name: close_account
      parameters:
        account_id: acc_oldsavings
        reason: "Customer requested closure"
      agent_role: admin_agent

Identity fields: agent_role, agent_id, on_behalf_of, parent_agent_id. Place them inside input alongside tool_name and parameters.

Parameter rules support custom_fn expressions for advanced validation:

tool_rules:
  rules:
    transfer_money:
      parameters:
        amount:
          type: number
          max_value: 10000
          custom_fn: "value > 0"
        to_account:
          type: string
          custom_fn: "value !== params.from_account"

Expression variables: value (current param), params.field (other params). Supports comparisons, logical ops, .length, .includes(), .startsWith().

CI/CD example

# GitHub Actions
name: Governance Check
on: [push]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate
        run: npx @driftgard/cli validate --pack ./control-packs/prod.yaml
      - name: Lint
        run: npx @driftgard/cli lint --pack ./control-packs/prod.yaml
      - name: Test
        run: npx @driftgard/cli test --pack ./control-packs/prod.yaml
      - name: Push
        run: npx @driftgard/cli push --pack ./control-packs/prod.yaml
        env:
          DRIFTGARD_API_KEY: ${{ secrets.DRIFTGARD_API_KEY }}
          DRIFTGARD_PROJECT_ID: ${{ secrets.DRIFTGARD_PROJECT_ID }}
      - name: Benchmark
        run: npx @driftgard/cli benchmark --max-violation-rate 0.05
        env:
          DRIFTGARD_API_KEY: ${{ secrets.DRIFTGARD_API_KEY }}
          DRIFTGARD_PROJECT_ID: ${{ secrets.DRIFTGARD_PROJECT_ID }}

Options

Environment variables

License

MIT