CLI Reference

Smoltbot CLI commands and usage

CLI Reference

The smoltbot CLI configures your local environment for transparent AI agent tracing and provides commands to query your agent’s transparency data.

Installation

npm install -g @mnemom/smoltbot

Commands

1. smoltbot init
2. Configure tracing for your AI agent. This command detects your configured AI provider API keys (Anthropic, OpenAI, Gemini) and configures your local environment to route API calls through the Mnemom gateway.
3. smoltbot init
   

4. What it does:
6. Options:
7. OptionDescription--gateway=<url>Use a custom gateway URL (for self-hosted deployments)
8. Example:
9. # Default setup — uses Mnemom hosted gateway
   smoltbot init
   
   # Self-hosted gateway
   smoltbot init --gateway=https://your-domain.com
   

10. smoltbot status
11. Show agent status, connected providers, and connection info.
12. smoltbot status
    

13. Output includes:
15. Example output:
16. Agent:    agent_abc123def456
    Gateway:  https://gateway.mnemom.ai
    Status:   Connected
    Providers:
      Anthropic  ✓ (Claude Opus 4.6)
      OpenAI     ✓ (GPT-5.2)
      Gemini     ✗ (not configured)
    Last seen: 2 minutes ago
    

17. smoltbot integrity
18. Display integrity score and verification statistics for your agent.
19. smoltbot integrity
    

20. Output includes:
22. Example output:
23. Integrity Score: 0.94 (94%)
    Traces verified: 1,247
    Violations:      12 (3 CRITICAL, 9 HIGH)
    Drift alerts:    0 active
    Window:          10 checkpoints, 2h retention
    

24. smoltbot logs
25. Show recent traces and actions.
26. smoltbot logs [-l N]
    

27. Options:
28. OptionDescriptionDefault-l NNumber of log entries to display10
29. Example:
30. # Show last 10 traces (default)
    smoltbot logs
    
    # Show last 50 traces
    smoltbot logs -l 50
    

31. Example output:
32. 2026-02-17 14:32:01  CLEAR      api_call    Claude Opus 4.6    "Search for documents"
    2026-02-17 14:31:45  CLEAR      api_call    Claude Opus 4.6    "Summarize results"
    2026-02-17 14:31:12  REVIEW     api_call    GPT-5.2            "Execute trade"
      └─ concern: autonomy_violation (HIGH) — action exceeds bounded_actions
    2026-02-17 14:30:58  CLEAR      api_call    Claude Opus 4.6    "Draft email"
    

33. smoltbot card show
34. Fetch your agent’s active alignment card and display it with colored, structured output showing values, autonomy envelope, forbidden actions, escalation triggers, and audit commitment.
35. smoltbot card show
    

36. Example output:
37. ═══════════════════════════════════════════════════
      Alignment Card  ac-a4c12709-v2
    ═══════════════════════════════════════════════════
    
      Version    0.1.0
      Issued     2026-02-21
      Expires    2026-08-21
    
      Values     transparency  honesty  harm_prevention
                 editorial_independence  source_attribution
                 investigative_rigor
      Hierarchy  lexicographic
    
      Bounded    inference  read  write  edit  exec
                 web_fetch  web_search
      Forbidden  fabricate_sources  impersonate_human  ...
      Escalation named_entity_critical → escalate
                 legal_claims_present → escalate
    
      Audit      ap-trace-v1 · 365 days · queryable · append_only
    

38. smoltbot card publish <file>
39. Read a JSON alignment card file, validate it against the AAP spec, confirm before publishing, and upload to your agent’s alignment card via the API. Optionally triggers re-verification of existing traces against the new card.
40. smoltbot card publish <file>
    

41. Options:
42. OptionDescription--no-verifySkip re-verification prompt after publish--yesSkip confirmation prompt
43. Example:
44. $ smoltbot card publish alignment-card.json
    
      Validating alignment-card.json...
      ✓ Valid JSON
      ✓ Required blocks present (principal, values, autonomy, audit)
      ✓ 6 declared values (3 standard, 3 custom with definitions)
      ✓ 7 bounded actions
      ✓ 2 escalation triggers (evaluable conditions)
      ✓ Card not expired
    
      Publish this card for agent smolt-a4c12709? (y/N) y
    
      ✓ Card published: ac-a4c12709-v2
      Re-verify existing traces against new card? (y/N) y
      ✓ 247 traces re-verified
    

45. smoltbot card validate <file>
46. Local-only validation with no API call. Checks AAP spec compliance. CI-friendly: exit code 0 on pass, 1 on fail.
47. smoltbot card validate <file>
    

48. Example:
49. $ smoltbot card validate alignment-card.json
    
      ✓ Valid JSON
      ✓ Required blocks: principal, values, autonomy_envelope, audit_commitment
      ✓ values.declared: 6 values (non-empty)
      ✓ Custom values defined: editorial_independence, source_attribution, investigative_rigor
      ✓ bounded_actions: 7 actions (non-empty)
      ✓ escalation_triggers: 2 triggers (evaluable conditions)
      ✓ expires_at: 2026-08-21 (valid)
    
      Card is valid.
    

50. smoltbot register <name>
51. Register a new named agent. Each named agent gets its own distinct identity and trace history, even when sharing the same API key. The name is stored on the server on first traced API call and displayed on the dashboard.
52. smoltbot register my-coder
    

53. Options:
54. OptionDescription--openclawConfigure using OpenClaw--standaloneConfigure standalone mode--set-defaultSet the new agent as default
55. Example:
56. # Register a new agent for coding tasks
    smoltbot register my-coder --openclaw
    
    # Register and set as default
    smoltbot register my-researcher --set-default
    

57. smoltbot agents
58. List all registered agents with their IDs, providers, and creation dates.
59. smoltbot agents
    

60. Example output:
61.   default (default)
        Agent ID:  smolt-a4c12709
        Provider:  openclaw
        Created:   2/7/2026
    
      my-coder
        Agent ID:  smolt-b8e34f21
        Provider:  openclaw
        Created:   2/23/2026
    
      Total: 2 agent(s)
    

62. smoltbot agents default <name>
63. Set the default agent used when no --agent flag is provided.
64. smoltbot agents default my-coder
    

65. smoltbot agents remove <name>
66. Remove a registered agent from the local configuration.
67. smoltbot agents remove my-coder
    

Global Options

Option	Description
--agent <name>	Select which agent to use for the command
--version	Show CLI version
--help	Show help text

Agent selection priority:

1. --agent <name> flag
2. SMOLTBOT_AGENT environment variable
3. Default agent from config

Example:

# Check status of a specific agent
smoltbot status --agent my-coder

# Use environment variable
SMOLTBOT_AGENT=my-coder smoltbot logs

# Default agent (no flag needed)
smoltbot status

Workflow

A typical workflow with the smoltbot CLI:

1. Set up tracing
2. smoltbot init
   

3. Verify your agent is connected
4. smoltbot status
   

5. Use your AI agent normally
6. Your API calls are automatically traced through the gateway. No code changes required.
7. Check integrity
8. smoltbot integrity
   

9. Register additional agents (optional)
10. smoltbot register my-researcher --openclaw
    smoltbot status --agent my-researcher
    

11. Review recent activity
12. smoltbot logs -l 20
    

13. Customize your alignment card (optional)
14. Create an alignment card JSON file and publish it:
15. smoltbot card validate my-card.json
    smoltbot card publish my-card.json
    

16. See the Card Management guide for how to build a card from scratch.
17. Define a governance policy (optional)
18. Create and publish a policy that maps your agent’s tools to alignment card capabilities:
19. smoltbot policy init
    # Edit policy.yaml to define capability mappings and forbidden rules
    smoltbot policy validate policy.yaml
    smoltbot policy publish policy.yaml
    

20. See the Policy CLI Reference for all policy subcommands and the Policy Management guide for a full walkthrough.
21. Link to your Mnemom account (optional)
22. Associate your agent with your Mnemom account for a private dashboard:

Policy Commands

The smoltbot policy subcommands manage governance policies for your agents. For full reference, see Policy CLI Reference.

Command	Description
policy init	Generate a starter policy.yaml
policy validate <file>	Local schema validation (CI-friendly exit codes)
policy publish <file>	Upload policy to agent
policy list	List published policies
policy test <file>	Dry-run against historical traces
policy evaluate	CI/CD gate evaluation

Supported Providers

The CLI automatically detects and configures tracing for these providers:

Provider	Models	Thinking/AIP	Auth Method
Anthropic	Claude Opus 4.6, Opus 4.5, Sonnet 4.5	Full (thinking blocks)	x-api-key
OpenAI	GPT-5.2, GPT-5.2 Pro, GPT-5	Via reasoning summaries	Authorization: Bearer
Gemini	Gemini 2.5 Pro, Gemini 3 Pro	Full (thought parts)	x-goog-api-key

Related

• Smoltbot Overview — Architecture and how it works
• Policy CLI Reference — Policy management commands
• Enforcement Modes — Configure violation response behavior