# CLI and machine API

`dsh-tool-chaos` is intentionally usable without a human-facing UI. Every automation-relevant command supports structured output or writes versioned artifacts.

## Command summary

### `doctor`

```bash
dsh-tool-chaos doctor [--profile name] [--json]
```

Checks Node, Git, npm, DSH, Codex, and the selected profile. The JSON report distinguishes:

- `readyForPlugin` — DSH can be started;
- `readyForExperiment` — both bundle rows are present;
- `readyForCodex` — Codex CLI is available.

### `setup`

```bash
dsh-tool-chaos setup [--profile name] [--source npm-or-path] [--codex] [--codex-dir path] [--json]
```

Idempotently installs and verifies the DSH bundle. With `--codex`, also installs the Codex plugin and a standalone `~/.agents/skills/dsh-chaos-test` fallback.

The default profile is derived from `sha256(realpath(cwd))`, so separate workspaces do not collide.

### `init`

```bash
dsh-tool-chaos init [path] --preset retry|timeout|nested|result-block|deny [--force]
```

Writes a complete dry-run DSH overlay with one narrow rule and the reporter enabled.

### `run`

```bash
dsh-tool-chaos run \
  --mode baseline|dry-run|experiment \
  --patch file \
  --task text \
  [--expect regex] \
  [--profile name] \
  [--source spec] \
  [--output dir] \
  [--timeout ms] \
  [--no-install] \
  [--include-output] \
  [--json]
```

The CLI passes the scenario as an ephemeral DSH `--patch` overlay; it does not persist experiment rules in the profile.

Mode contracts:

| Mode | Required evidence | Success verdict |
|---|---|---|
| `baseline` | process/assertion success and no chaos decision | `baseline-passed` |
| `dry-run` | process/assertion success and one or more `dryRun: true` decisions, no real injection | `preview` |
| `experiment` | process/assertion success and one or more real injections | `passed` |

### Installation primitives

```bash
dsh-tool-chaos install-plugin [--profile name] [--source spec] [--json]
dsh-tool-chaos install-skill [--global | --project path]
dsh-tool-chaos install-codex-plugin [--dir path] [--json]
```

Use `setup` for normal onboarding and the primitives for debugging or managed environments.

### Prompt and Codex automation

```bash
dsh-tool-chaos prompt --lang en|zh "requirement"
dsh-tool-chaos codex [--cwd path] [--json] "requirement"
```

`prompt` prints a reusable autonomous execution prompt. `codex` supplies it to an ephemeral `codex exec` run.

### Repository verification

```bash
dsh-tool-chaos verify --json
```

Validates package, Codex marketplace/plugin, Skill frontmatter, bilingual README, and governance files.

## JSON stability

- Human prose may improve between patch releases.
- Fields documented in `docs/REPORT-SCHEMA.md` are the machine contract.
- New optional fields may be added without a major version.
- Removing or changing field meaning requires a schema-version and SemVer change.

## Exit codes

| Code | Meaning |
|---:|---|
| 0 | command succeeded; run produced `baseline-passed`, `preview`, or `passed` |
| 1 | operational error or `failed` run |
| 2 | unsupported environment or `inconclusive` run |
| 3 | plugin installation could not be verified in effective DSH config |
| 127 | CLI or skill wrapper could not start a required DSH, Codex, or npx command |