Kindred CLI

Command-line tool for testing AI agents with deterministic fault injection and trace analysis.

Installation

# Global install (recommended)
npm install -g kindred-cli

# One-off use
npx kindred-cli --help

Requires Node.js 18+.

Quick Start

1. Authenticate

kindred login -u https://your-kindred-api.example.com

Stores API key in ~/.kindred/config.json.

2. Register an Agent

kindred agent register           # Uses agent.yaml in current directory
kindred agent register path/to/agent.yaml

Copy the bearer token shown and set it in your agent server as KINDRED_BEARER_TOKEN.

3. Configure Agent Endpoint

kindred agent set https://your-agent.com/run-step YOUR_BEARER_TOKEN
kindred agent test  # Verify connectivity

4. Run Test Suites

kindred run resiliency   # Test fault tolerance
kindred run security     # Test security boundaries

5. Analyze Traces

kindred trace list                          # List recent runs
kindred trace show <run-id>                 # View full trace
kindred trace show <run-id> --diagnosis     # Get root cause analysis

Commands

Authentication

| Command | Description | |---------|-------------| | kindred login [-u <url>] | Authenticate and store API key | | kindred logout | Remove stored credentials | | kindred whoami | Show current authenticated user |

Agent Management

| Command | Description | |---------|-------------| | kindred agent register [yaml] | Register agent from YAML config | | kindred agent set <url> <token> | Save agent URL and token | | kindred agent show | Display saved agent config | | kindred agent test | Test agent connectivity | | kindred agent clear | Remove saved agent config |

Running Tests

kindred run <suite> [options]

Suites: resiliency, security, drift-stability, long-horizon

Options:

• --agent-url <url> - Agent endpoint URL
• --agent-token <token> - Bearer token
• --save-agent - Save URL/token for future runs
• --test-case-id <id> - Run specific test case only

Trace Analysis

kindred trace show <run-id> [options]
kindred trace list [options]

Display Options:

| Option | Description | |--------|-------------| | --summary | Brief summary only | | --step <n> | Show specific step | | --test-case <id> | Show specific test in suite | | --json | Raw JSON output |

Debugging Options:

| Option | Description | |--------|-------------| | -v, --verbose | Full JSON with syntax highlighting | | --expand <field> | Expand: observation, result, or all | | --filter <criteria> | Filter: faults, failures, errors, tool=<name> | | --timing | Step timing analysis table | | --diagnosis | Root cause analysis with fix suggestions | | --chain | Fault-to-failure critical path | | --diff | Observation changes between steps | | --metrics | Test metrics (recovery time, entropy) |

Examples:

# Get diagnosis for a failed run
kindred trace show run_abc123 --diagnosis

# Filter to only steps with faults
kindred trace show run_abc123 --filter faults

# Verbose view of a specific step
kindred trace show run_abc123 --step 3 --verbose

# View timing breakdown
kindred trace show run_abc123 --timing

# See what changed between steps
kindred trace show run_abc123 --diff

Configuration

All configuration is stored in ~/.kindred/config.json:

• API URL and authentication
• Saved agent endpoint and token

Development

# Build
npm run build

# Watch mode
npm run dev

# Publish (from package directory)
npm publish --access public

Requirements

• Node.js 18+
• Agent URL must be HTTPS for non-localhost (use ngrok for local development)

License

MIT