CLI reference

Every command, flag and default below is read directly from the CLI source, so it cannot drift from the shipped behaviour.

Global options

Flag	Description	Default
`-V, --version`	output the version number	—
`-v, --verbose`	verbose output	—
`--config <path>`	path to config file	`"./samaritan.config.yaml"`

Commands

Command	Description
`init`	Initialize a new SAMARITAN project
`operation`	Create a new operation
`validate`	Validate operation definitions
`generate`	Generate documentation and reports
`run`	Execute an operation
`resume`	Resume a paused or failed operation session
`sessions`	List saved run sessions from ~/.samaritan/sessions/ (resumable by default)
`schema`	Export operation JSON schema
`diff`	Compare how steps render across two environments
`report`	Generate a Markdown evidence report from a JSONL session log
`postmortem`	Author postmortem / incident report (RCA) documents
`qrh`	Quick Reference Handbook for emergency procedures
`support`	Get support information

`init`

Initialize a new SAMARITAN project

bash

samaritan init [options]

Flag	Description	Default
`--existing`	Add SAMARITAN to existing project	—

`operation`

Create a new operation

bash

samaritan operation [options]

Flag	Description	Default
`--template <name>`	Use a template (deployment, backup, incident-response, maintenance)	—

`validate`

Validate operation definitions

bash

samaritan validate [options] <file>

Argument	Required	Description
`file`	yes	Path to operation YAML file

Flag	Description	Default
`--strict`	Enable strict validation with best practices	—
`-e, --env <environment>`	Validate for specific environment	—
`-v, --verbose`	Verbose output	—
`--lint`	Lint step commands/scripts with shellcheck (skipped if not installed)	—

`generate`

Generate documentation and reports

bash

samaritan generate <subcommand>

`generate manual`

Generate operation manual

bash

samaritan generate manual [options] <operation>

Argument	Required	Description
`operation`	yes

Flag	Description	Default
`-o, --output <file>`	Output file path	—
`-f, --format <format>`	Output format (markdown, html, confluence, adf)	`"markdown"`
`-e, --env <environment>`	Generate for specific environment	—
`--all-envs`	Generate one manual per environment defined in the operation	—
`--output-dir <dir>`	Directory for --all-envs output (default: current directory)	—
`--prefix <name>`	Base filename for --all-envs output (default: operation file name); env name is appended as suffix	—
`--resolve-vars`	Resolve variables to actual values instead of showing placeholders	—
`--gantt`	Include Mermaid Gantt chart for timeline visualization	—
`--run <manifest>`	Path to a run manifest YAML to overlay run-specific evidence	—

`generate docs`

Generate comprehensive documentation

bash

samaritan generate docs [options] <operation>

Argument	Required	Description
`operation`	yes

Flag	Description	Default
`-o, --output <file>`	Output file path	—
`-f, --format <format>`	Output format (markdown, html, confluence, adf, pdf)	`"markdown"`
`-e, --env <environment>`	Generate for specific environment	—
`--resolve-vars`	Resolve variables to actual values instead of showing placeholders	—

`generate postmortem`

Generate a postmortem / incident report (RCA) document

bash

samaritan generate postmortem [options] <postmortem>

Argument	Required	Description
`postmortem`	yes

Flag	Description	Default
`-o, --output <file>`	Output file path (default: stdout)	—
`-f, --format <format>`	Output format (markdown, confluence, adf)	`"markdown"`

`generate schedule`

Generate execution timeline and Gantt chart

bash

samaritan generate schedule [options] <operation>

Argument	Required	Description
`operation`	yes

Flag	Description	Default
`-o, --output <file>`	Output file path	—

`run`

Execute an operation

bash

samaritan run [options] <operation>

Argument	Required	Description
`operation`	yes	Operation file path

Flag	Description	Default
`-e, --env <environment>`	Target environment	—
`--environment <environment>`	Target environment (alias for --env)	—
`--auto-approve`	Auto-approve all manual steps and approvals	—
`--dry-run`	Preview full operation plan without executing	—
`--mock`	Replay each step expect against its evidence.results output (no tmux); non-zero exit on failure	—
`-m, --mode <mode>`	Execution mode: sidecar \| manual \| automatic \| hybrid	`"sidecar"`
`--attach <tmux-target>`	Attach to an existing tmux pane for sidecar capture (e.g. mysession:0.0)	—
`--var <key=value>`	Override variable values	—
`-v, --verbose`	Verbose output	—
`--continue-on-error`	Continue execution even if steps fail	—
`--report <dir>`	Write Markdown evidence report to directory	—
`--from-step <number>`	Start at a specific step number; earlier steps are recorded as skipped	—
`--no-require-evidence`	Allow completing a step whose evidence.required is true without capturing evidence	—
`--pic [name]`	Focus on steps assigned to this PIC (default: $USER); other operators' steps are auto-skipped	—
`--no-skip-others`	In --pic focus mode, keep other operators' steps visible/runnable instead of auto-skipping	—

`resume`

Resume a paused or failed operation session

bash

samaritan resume [options] <session-id>

Argument	Required	Description
`session-id`	yes	Session ID to resume

Flag	Description	Default
`-v, --verbose`	Verbose output	—
`--auto-approve`	Auto-approve remaining manual steps	—
`--from-step <number>`	Resume from specific step number	—
`--attach <tmux-target>`	Sidecar: capture from this tmux pane (default: the pane the run was attached to)	—
`--no-require-evidence`	Allow completing a step whose evidence.required is true without capturing evidence	—
`--pic [name]`	Focus on steps assigned to this PIC (default: $USER); other operators' steps are auto-skipped (not persisted — re-supply on resume)	—
`--no-skip-others`	In --pic focus mode, keep other operators' steps visible/runnable instead of auto-skipping	—

`sessions`

List saved run sessions from ~/.samaritan/sessions/ (resumable by default)

bash

samaritan sessions [options]

Flag	Description	Default
`-a, --all`	Include completed and cancelled sessions	—

`schema`

Export operation JSON schema

bash

samaritan schema [options]

Flag	Description	Default
`-o, --output <file>`	Output file (default: stdout)	—
`-f, --format <format>`	Output format: json or yaml	`"json"`

`diff`

Compare how steps render across two environments

bash

samaritan diff [options] <operation> <envA> <envB>

Argument	Required	Description
`operation`	yes	Path to operation YAML file
`envA`	yes	First environment to compare
`envB`	yes	Second environment to compare

Flag	Description	Default
`-o, --output <file>`	Write Markdown report to file (in addition to terminal output)	—

`report`

Generate a Markdown evidence report from a JSONL session log

bash

samaritan report <subcommand> [options] <jsonl>

Argument	Required	Description
`jsonl`	yes	Path to the JSONL session log file

Flag	Description	Default
`-o, --output <file>`	Output file path (default: stdout)	—

`report merge`

Merge multiple run sessions of the same operation into one consolidated report

bash

samaritan report merge [options] <sessions>

Argument	Required	Description
`sessions`	yes	Two or more session IDs to merge

Flag	Description	Default
`-o, --output <file>`	Output file path (default: stdout)	—

`postmortem`

Author postmortem / incident report (RCA) documents

bash

samaritan postmortem <subcommand>

`postmortem from-run`

Seed a postmortem YAML from a captured run record (events.jsonl or session id)

bash

samaritan postmortem from-run [options] <session-or-jsonl>

Argument	Required	Description
`session-or-jsonl`	yes

Flag	Description	Default
`-o, --output <file>`	Output file path (default: stdout)	—

`postmortem init`

Write a blank postmortem authoring template

bash

samaritan postmortem init [options]

Flag	Description	Default
`-o, --output <file>`	Output file path (default: stdout)	—

`qrh`

Quick Reference Handbook for emergency procedures

bash

samaritan qrh <subcommand>

`qrh search`

Search emergency procedures

bash

samaritan qrh search [options] <query>

Argument	Required	Description
`query`	yes

Flag	Description	Default
`-p, --priority <priority>`	Filter by priority (P0, P1, P2, P3)	—
`-c, --category <category>`	Filter by category (incident, alert, maintenance, emergency)	—
`-l, --limit <number>`	Limit number of results	—
`-v, --verbose`	Show detailed information	—

`qrh list`

List all emergency procedures

bash

samaritan qrh list [options]

Flag	Description	Default
`-p, --priority <priority>`	Filter by priority (P0, P1, P2, P3)	—
`-c, --category <category>`	Filter by category (incident, alert, maintenance, emergency)	—
`-v, --verbose`	Show detailed information	—

`qrh run`

Execute an emergency procedure

bash

samaritan qrh run [options] <procedure-id>

Argument	Required	Description
`procedure-id`	yes

Flag	Description	Default
`-e, --env <environment>`	Target environment	`"emergency"`
`--auto-approve`	Auto-approve manual steps	—
`--dry-run`	Show what would be executed without running	—
`-v, --verbose`	Verbose output	—

`qrh show`

Show detailed information about a procedure

bash

samaritan qrh show <procedure-id>

Argument	Required	Description
`procedure-id`	yes

`support`

Get support information

bash

samaritan support

CLI reference ​

Global options ​

Commands ​

init ​

operation ​

validate ​

generate ​

generate manual ​

generate docs ​

generate postmortem ​

generate schedule ​

run ​

resume ​

sessions ​

schema ​

diff ​

report ​

report merge ​

postmortem ​

postmortem from-run ​

postmortem init ​

qrh ​

qrh search ​

qrh list ​

qrh run ​

qrh show ​

support ​

CLI reference

Global options

Commands

`init`

`operation`

`validate`

`generate`

`generate manual`

`generate docs`

`generate postmortem`

`generate schedule`

`run`

`resume`

`sessions`

`schema`

`diff`

`report`

`report merge`

`postmortem`

`postmortem from-run`

`postmortem init`

`qrh`

`qrh search`

`qrh list`

`qrh run`

`qrh show`

`support`