@reaatech/agent-chaos-cli

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Command-line interface for agent-chaos. Validate scenario files against the JSON Schema, generate scenario templates from a built-in library, run chaos scenarios with hot-reload support, and initialize new chaos testing projects — all from your terminal.

Installation

npm install -g @reaatech/agent-chaos-cli
# or run without global install
npx @reaatech/agent-chaos-cli validate ./scenario.yaml

Feature Overview

• 4 commands — init, generate, validate, and run for end-to-end scenario management
• 5 built-in templates — network-degradation, provider-outage, rate-limit-storm, token-exhaustion, and contradiction
• Hot reload — --watch flag reloads scenarios on file changes without restarting
• JSON and YAML — both .yaml/.yml and .json scenario formats supported
• Programmatic API — command functions exported for use in scripts and CI
• CI/CD ready — zero-install usage via npx; validation exits with non-zero on failure

Quick Start

# Initialize a new project
agent-chaos init
 
# Generate a scenario template
agent-chaos generate network-degradation --output ./scenarios
 
# Validate your scenario
agent-chaos validate ./scenarios/network-degradation.yaml
 
# Run a scenario (10 sample tool calls with fault injection)
agent-chaos run ./scenarios/network-degradation.yaml

Commands

init

Creates a scenarios/ directory and a sample hello-world.yaml scenario (latency fault, 100–500ms, 10% probability).

agent-chaos init

generate

Copies a built-in template from @reaatech/agent-chaos-scenarios/templates/ to your output directory.

agent-chaos generate <type> [--output <dir>]

Available template types:

validate

Validates a scenario file against the built-in JSON Schema.

agent-chaos validate <file>

Supports .yaml, .yml, and .json. Prints a green checkmark on success or lists each validation error with its JSON path on failure. Exits with code 1 on validation failure.

run

Loads a scenario, registers it with the chaos engine, and runs 10 sample tool calls to demonstrate fault injection.

agent-chaos run <scenario> [--watch]

The run command prints each tool call’s pass/fail status and a summary with total calls, faults injected, registered injectors, and loaded scenarios.

Programmatic API

All command functions are exported for use in scripts and CI pipelines:

import {
  runCommand,
  validateCommand,
  generateCommand,
  initCommand,
} from "@reaatech/agent-chaos-cli";
 
await initCommand();
await generateCommand("network-degradation", { output: "./scenarios" });
await validateCommand("./scenarios/network-degradation.yaml");
await runCommand("./scenarios/network-degradation.yaml", { watch: true });

Function Signatures

function initCommand(): Promise<void>;
function generateCommand(type: string, options: { output?: string }): Promise<void>;
function validateCommand(filePath: string): Promise<void>;
function runCommand(scenarioPath: string, options: { watch?: boolean }): Promise<void>;

CI/CD Integration

Validate scenarios in CI without a global install:

npx @reaatech/agent-chaos-cli validate ./scenarios/*.yaml

Or via GitHub Actions:

steps:
  - run: npx @reaatech/agent-chaos-cli validate ./scenarios/network-degradation.yaml

Related Packages

• @reaatech/agent-chaos-core — Core fault injection engine
• @reaatech/agent-chaos-scenarios — Scenario loader, schema validator, and templates

License

MIT