CLI Tools

COMMAND LINE

The ACP CLI provides utilities for trace inspection, replay, testing, and analysis. All commands operate on recorded artifacts without executing agent code.

acp [command] [options]

acp inspect

View trace details and step contents

acp replay

Verify deterministic reproduction

acp test

Run behavioral tests against traces

acp analyze

Detect inefficiencies and issues

acp list

List all available traces

acp export

Export trace to various formats

CLI Tools

INSPECT

Interactively explore trace contents in the terminal.

View Trace Summary

acp inspect traces/run_abc123/

Displays run metadata, step count, status, and duration.

View Specific Step

# View step 5 with full input/output

acp inspect traces/run_abc123/ --step 5

# View step with memory snapshot

acp inspect traces/run_abc123/ --step 5 --memory

Filter by Phase

# Show only tool calls

acp inspect traces/run_abc123/ --phase tool

# Show only errors

acp inspect traces/run_abc123/ --status error

CLI Tools

REPLAY

Verify deterministic reproduction of agent execution from recorded artifacts.

# Replay and verify all steps

acp replay traces/run_abc123/

# Replay with verbose output

acp replay traces/run_abc123/ --verbose

# Replay and compare to another run

acp replay traces/run_abc123/ --compare traces/run_xyz789/

What Replay Does

• Reads from steps.jsonl and snapshots/
• Feeds recorded outputs back to the execution model
• Never calls external APIs or LLMs
• Verifies state consistency at each step
• Reports any divergence from expected behavior

CLI Tools

TEST

Run behavioral tests against recorded traces using YAML test definitions.

# Run all tests in tests/ directory

acp test traces/run_abc123/

# Run specific test file

acp test traces/run_abc123/ --file tests/booking.yaml

# Run with detailed output

acp test traces/run_abc123/ --verbose

Example Test File

# tests/booking.yaml
name: "Restaurant Booking Tests"
description: "Verify booking agent behavior"

tests:
  - name: "Search must be called"
    assertions:
      - type: tool_called
        params:
          tool: search_restaurants
          minTimes: 1

  - name: "Booking completes successfully"
    assertions:
      - type: tool_called
        params:
          tool: book_restaurant
          minTimes: 1
      - type: state_contains
        params:
          key: "booking_confirmed"
          value: true

  - name: "Reasonable step count"
    assertions:
      - type: max_steps
        params:
          count: 15

Available Assertions

Type	Description	Params
`tool_called`	Verify a tool was called	`tool, minTimes`
`tool_not_called`	Verify a tool was NOT called	`tool`
`max_steps`	Maximum step count	`count`
`min_steps`	Minimum step count	`count`
`state_contains`	Final state has key/value	`key, value`
`output_matches`	Output matches pattern	`step, pattern`

CLI Tools

ANALYZE

Automatically scan traces for inefficiencies, anti-patterns, and potential issues.

# Run full analysis

acp analyze traces/run_abc123/

# Generate HTML report

acp analyze traces/run_abc123/ --format html --output report.html

# JSON output for CI/CD

acp analyze traces/run_abc123/ --format json

Detected Warnings

high_step_count

Too many steps executed

Agent exceeds expected step limits, potentially indicating infinite loops or poor decision-making.

memory_growth

Memory growing without cleanup

Memory footprint continuously increases, risking context window overflow.

repeated_tool_calls

Redundant tool invocations

Same tool called with identical parameters multiple times.

long_duration

Steps taking too long

Individual steps exceed expected duration thresholds.

error_rate

High error percentage

Significant portion of steps result in errors.