@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

Inline Enforcement

The CLI manages the control packs and tests that DriftGard enforces at runtime. Inline model traffic itself should go through the SDKs or the OpenAI-compatible Gateway endpoint, not through the CLI:

Application -> DriftGard Gateway -> LLM provider -> DriftGard Gateway -> Application

Use:

• Node SDK: gatewayChatCompletions() and streamGatewayChatCompletions()
• Python SDK: gateway_chat_completions() and stream_gateway_chat_completions()
• HTTP: POST /gateway/v1/chat/completions

Use the CLI to validate, lint, test, promote, and activate the policies that Inline Enforcement applies.

Governed Knowledge

Governed Knowledge sources, document upload, S3 and Confluence connector sync, API document feeds, retrieval replay, and gateway knowledge injection are managed through the DriftGard SDKs and API. The CLI remains focused on control-pack governance-as-code workflows.

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

Benchmark runs execute against the project backend, so project-level model governance also applies. If a benchmark item uses a model_id that is not approved for the project, the result can include:

{
  "clause_id": "MODEL_NOT_APPROVED",
  "category": "model_governance",
  "source": "model_policy"
}

Whether that item is allowed with a flag or blocked depends on the project's model governance action. Model IDs are exact matches; gpt-4o and openai/gpt-4o are different IDs unless both are approved.

Decision Metadata rules are also applied by backend benchmark runs. Matching metadata appears under evaluation.decision_metadata in item details for downstream workflow hints, but it does not affect the benchmark pass/fail gate.

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

driftgard test --pack validates the control pack/evaluator behavior from the pack file. It does not apply project-level Model Governance or Decision Metadata unless the command is run through a backend benchmark path, because those runtime settings live in project settings rather than inside the control pack.

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: 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 }}
      - 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

| Flag | Description | |---|---| | --project-id <id> | Project ID (or set DRIFTGARD_PROJECT_ID) | | --pack <file> | Path to control pack file (.json or .yaml) | | --format <fmt> | Output format: json or yaml (default: yaml) | | --version <n> | Version number for activate or promote | | --pack-id <id> | Control pack ID for activate or promote | | --from-project <id> | Source project ID (for promote) | | --to-project <id> | Target project ID (for promote) | | --activate | Activate in target after promote |

Environment variables

| Variable | Description | |---|---| | DRIFTGARD_API_KEY | API key (required for remote commands) | | DRIFTGARD_BASE_URL | API base URL (default: https://api.driftgard.com) | | DRIFTGARD_PROJECT_ID | Default project ID |

License

MIT