Kindred CLI

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

Installation

``bash


Global install (recommended)

npm install -g kindred-cli

One-off use

npx kindred-cli --help
`

Requires Node.js 18+.

Quick Start

$3

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

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

$3

`bash
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

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

$3

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

$3

`bash
kindred trace list # List recent runs
kindred trace show # View full trace
kindred trace show --diagnosis # Get root cause analysis
`

Commands

$3

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

$3

| Command | Description |
|---------|-------------|
| kindred agent register [yaml] | Register agent from YAML config |
| kindred agent set | 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 |

$3

`bash
kindred run [options]
`

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

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

$3

`bash
kindred trace show [options]
kindred trace list [options]
`

Display Options:

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

Debugging Options:

| Option | Description |
|--------|-------------|
| -v, --verbose | Full JSON with syntax highlighting |
| --expand | Expand: observation, result, or all |
| --filter | Filter: faults, failures, errors, tool= |
| --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:

`bash


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

`bash


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