Skip to main content

​
Policy CLI Reference

The smoltbot policy commands manage governance policies for your agents. Policies define which tools an agent can use, how unmapped tools are handled, and what actions are forbidden — bridging the gap between abstract alignment card declarations and concrete tool usage.

​
Commands

1
smoltbot policy init
2
Generate a starter policy.yaml file with commented examples.
3
smoltbot policy init
4
What it does:
5
  • Creates a policy.yaml in the current directory
  • Includes commented examples for capability_mappings, forbidden rules, escalation_triggers, and defaults
  • Pre-fills with sensible defaults (warn mode, 24h grace period, deny unmapped tools)
    • 6
    Example output:
    7
    ✓ Created policy.yaml
  Edit the file to define your capability mappings and forbidden rules.
  Run 'smoltbot policy validate policy.yaml' to check your policy.
    8
    smoltbot policy validate <file>
    9
    Local-only schema validation. No API call. CI-friendly exit codes.
    10
    smoltbot policy validate policy.yaml
    11
    Exit codes:
    12
  • 0 — Valid policy
  • 1 — Validation errors
    • 13
    Example output (success):
    14
    Validating policy.yaml...
  ✓ Schema version: 1.0
  ✓ Meta: name="support-agent-policy", scope=agent
  ✓ Capability mappings: 4 capabilities, 12 tool patterns
  ✓ Forbidden rules: 3 rules
  ✓ Escalation triggers: 2 triggers
  ✓ Defaults: unmapped=deny, enforcement=warn, grace=24h

Policy is valid.
    15
    Example output (failure):
    16
    Validating policy.yaml...
  ✗ forbidden[1].severity: must be one of: critical, high, medium, low
  ✗ defaults.unmapped_tool_action: required field missing

2 errors found. Policy is invalid.
    17
    smoltbot policy publish <file>
    18
    Upload a policy to an agent. Validates locally first.
    19
    smoltbot policy publish policy.yaml
    20
    Options:
    21
    OptionDescription--agent <name>Target agent (default: current agent)--yesSkip confirmation prompt
    22
    Example output:
    23
    Validating policy.yaml...
  ✓ Valid (4 capabilities, 3 forbidden rules)

Publish this policy for agent smolt-a4c12709? (y/N) y

  ✓ Policy published (version 3)
  Previous policy archived.
    24
    smoltbot policy list
    25
    List published policies for your agent and organization.
    26
    smoltbot policy list
    27
    Example output:
    28
    Organization Policy:
  Name:     org-default-policy
  Scope:    org
  Version:  2
  Updated:  2026-02-20

Agent Policy (smolt-a4c12709):
  Name:     support-agent-policy
  Scope:    agent
  Version:  3
  Updated:  2026-02-25

Resolved policy: org + agent merged (agent strengthens org defaults)
    29
    smoltbot policy test <file>
    30
    Dry-run a policy against historical traces. Shows what violations WOULD have been flagged.
    31
    smoltbot policy test policy.yaml
    32
    Options:
    33
    OptionDescription--agent <name>Target agent--limit <N>Number of recent traces to test (default: 50)
    34
    Example output:
    35
    Testing policy.yaml against 50 recent traces...

  Trace tr-abc123 (2026-02-25 14:32):
    ⚠ UNMAPPED_TOOL: mcp__slack__post_message (warn)
    ⚠ UNMAPPED_TOOL: mcp__slack__read_channel (warn)

  Trace tr-def456 (2026-02-25 14:28):
    ✗ FORBIDDEN: mcp__filesystem__delete (critical)
      Reason: File deletion not permitted

Summary:
  50 traces analyzed
  1 would fail, 1 would warn, 48 would pass
  2 unmapped tools discovered
    36
    smoltbot policy evaluate
    37
    Run policy evaluation as a CI/CD gate. Evaluates the agent’s current resolved policy against recent activity.
    38
    smoltbot policy evaluate
    39
    Exit codes:
    40
  • 0 — All evaluations pass
  • 1 — One or more evaluations fail
    • 41
    Options:
    42
    OptionDescription--agent <name>Target agent--format <json|text>Output format (default: text)
    43
    Example output:
    44
    Evaluating policy for agent smolt-a4c12709...

  Verdict: PASS
  Violations: 0
  Warnings: 2
  Coverage: 85% (17/20 card actions mapped)

  Warnings:
    ⚠ 2 unmapped tools in grace period (expires in 18h)

    ​
    Global Options

    All policy commands support:
    OptionDescription
    --agent <name>Select which agent to use for the command
    --helpShow help for the subcommand

    ​
    See Also