Commands

Reference commands and operational entry points used in WitnessOps workflows.

This page is the command contract for operators running governed workflows and reviewers checking command-linked artifacts.

Quick reference links

1. Problem this page solves

Command names are easy to remember; command semantics are where drift happens.

This page fixes that by defining:

exact command entry points
usage boundaries for governed vs exception paths
expected artifacts and observable outputs for review

2. Audience task and expected outcome

After this page:

operators can run the five-command lifecycle without guessing side effects
approvers/reviewers can map command actions to state.json, receipt.json, and run artifacts
both lanes can separate command guarantees from broader policy or verification claims

3. Command surface and lifecycle order

The command surface is intentionally narrow:

new-engagement
runbook-exec
runbook-state
runbook-approve
runbook-resume

Use this order for normal governed execution. Repeated runbook-state checks are expected; repeated runbook-resume is safe for interrupted runs.

4. Command semantics, boundaries, and outputs

`new-engagement`

bash automation/helpers/new-engagement.sh <engagement-name>

Semantics: Initializes an engagement workspace at ops/engagements/<engagement-name>/.

Expected outputs:

ops/engagements/<engagement-name>/
├── scope/
├── recon/
├── scans/
├── loot/
├── notes/
└── report/

Usage boundary: This command does not set scope or execute runbooks. Populate scope/in-scope.txt before runbook-exec.

`runbook-exec`

bash automation/helpers/runbook-exec.sh <runbook-id> \
  --target <target> \
  --engagement <engagement-name>

Semantics: Validates runbook inputs, creates a timestamped run directory, enforces scope by default, executes ordered steps, and emits receipt-linked artifacts when the run reaches a terminal state.

Expected outputs: Run directory under ops/engagements/<engagement>/report/drafts/ with state.json, manifest.json, hash-manifest.txt, runbook-summary.md, step logs, and receipt.json at terminal completion.

Options:

Flag	Purpose
`--target`	Primary target for the runbook. Required.
`--engagement`	Engagement workspace name. Required.
`--no-scope`	Bypass scope enforcement. Exception path only.
`--lab`	Mark the run as lab execution.

Usage boundary: --no-scope and --lab are not normal production-governed paths. Review Lab Mode and Scope Bypass before use.

`runbook-state`

bash automation/helpers/runbook-state.sh <engagement-name> <run-id>

Semantics: Read-only state inspection for a run.

Expected outputs: Formatted status on stdout (status, completed steps, pending step/gate). With --json, raw state.json.

Flag	Purpose
`--json`	Output raw state JSON instead of formatted summary.

Usage boundary: This command does not mutate run state, approve gates, or resume execution.

`runbook-approve`

bash automation/helpers/runbook-approve.sh <engagement-name> <run-id> --approve

Semantics: Writes an explicit approval event for the currently gated step in paused state.

Expected outputs: Updated state.json approval record (step, approver identity, timestamp), later embedded in receipt.json.

Flag	Purpose
`--approve`	Confirm approval action. Required.
`--by <operator>`	Record specific approver identity. Defaults to current operator identity.

Usage boundary: Approval records permission; they do not execute the gated step. Use runbook-resume to continue.

`runbook-resume`

bash automation/helpers/runbook-resume.sh <engagement-name> <run-id>

Semantics: Continues from the next incomplete step in state.json. If a step was interrupted while running, it restarts that step from the beginning.

Expected outputs: Additional step artifacts in the same run directory and final receipt.json when terminal.

Usage boundary: Resume does not bypass future gates or scope checks; it re-enters governed step flow.

5. Explicit scope limits and non-claims

This page defines command behavior only. It does not:

replace Governance, Authorization Model, or escalation policy
claim canonical bundle-verification or retained-reference corpus semantics as part of this command contract
prove tool correctness, operator/approver judgment quality, or business-impact conclusions
expose internal-only proof implementation detail beyond operator/reviewer-visible artifacts

6. Operator and reviewer crosslinks

Operator lane

Approver/reviewer lane

7. Next-page handoff

Next, read Proof Artifact Classes to align command outputs with current artifact names, ownership lanes, and status boundaries.