Commands

This page separates the @witnessops/cli command-line client from the witnessops-offsec runbook helpers below. They are different toolchains with different authority and outputs.

@witnessops/cli tools

The package is private source distributed as an operator-supplied assisted-pilot archive; it has no public npm installer. In an approved repository checkout with Node.js 22, use node packages/wops-cli/src/main.mjs in place of the installed wops command shown below. Check that an installed wops belongs to @witnessops/cli before using it; the name alone does not identify a package. Source availability does not establish that an app service or pilot runtime is deployed.

Authentication

Start with CLI setup and authentication. From the source checkout:

node packages/wops-cli/src/main.mjs auth login
node packages/wops-cli/src/main.mjs auth status
node packages/wops-cli/src/main.mjs auth logout

Login targets https://app.witnessops.com by default, accepts --server URL for an approved app endpoint, and binds the selected workspace. Status checks current server access; logout removes the local credential and attempts revocation. Login authorizes a CLI session, not collection or signing. Use Account and CLI help for expired sessions, role restrictions or access problems.

Local agent and MCP observation

node packages/wops-cli/src/main.mjs agent inspect --help
node packages/wops-cli/src/main.mjs agent inspect --output ./agent-observation.json

agent inspect checks fixed agent executable names in bounded PATH locations using file metadata. It reads MCP declarations only from up to four explicitly selected JSON files passed with --mcp-config FILE; do not select credential files. It writes a new, private agent-observation.json by default, or a new file at --output FILE, and refuses to overwrite an existing file. Review the record's scope, unknowns, failures and retained source paths before sharing it. Exit 0 means the selected checks completed, 2 means partial or unsupported with a record, and 1 means invalid invocation or output failure. None is a security verdict.

Agent Action Security Review fit check

node packages/wops-cli/src/main.mjs review request --help
node packages/wops-cli/src/main.mjs review request

review request targets https://witnessops.com by default and accepts --server URL for an approved public-site endpoint. It prompts in a terminal for name, business email, optional organisation, locale and a short description of one consequential action. It displays the request and sends it only after an explicit y confirmation. The request is a non-secret fit check: do not enter credentials, logs, customer evidence or production data. A successful response reports that mailbox verification was issued; delivery and verification remain separate. It is not a booking or permission to start a review. The command does not read or upload the local observation record. See the Buyer path for the subsequent boundary.

Assisted Linux server check

node packages/wops-cli/src/main.mjs server check --help

The installed pilot's sudo wops server check uses a separate root-owned launcher and Local Audit runtime. A real check requires current app authorization with the server-check scope plus separately approved asset, collection scope and a time window of at most 30 minutes. It accepts --starts-at UTC --ends-at UTC for an approved window. It performs read-only collection and an upload; signing, remediation and arbitrary scanning are outside this command. The retire subcommand is a separate guarded action for an eligible retained check before capture upload or finalization. The source checkout and CLI login alone do not enable either operation. Read the pilot CLI contract and wops server check --help before an authorized pilot action.

Separate witnessops-offsec runbook helpers

The remainder describes the witnessops-offsec engagement toolchain, not @witnessops/cli. Its helper scripts are not supplied by this web repository. Use them only with that separate toolchain, its current contract and approved scope. These are shell helpers, not wops subcommands; they do not install the app or grant workspace access. Their state.json, receipt.json and run artifacts belong to that runbook toolchain, not to the app CLI commands above.

Fleet and mesh operators (not this public site)

Public buyer docs describe the proof-package path only. Fleet / mesh operators use internal OffSec mesh documentation and tooling that is not published on this docs site and is not part of the public product contract.

The runbook helper commands below apply to the witnessops-offsec engagement layout (ops/engagements/) when that layout is in use. They are not a public hunt loop and do not replace the buyer proof path on /verify.

Helper lifecycle order

The runbook helper surface is intentionally narrow:

1. new-engagement
2. runbook-exec
3. runbook-state
4. runbook-approve
5. runbook-resume

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

Helper 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: a 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:

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, such as status, completed steps, and pending step or gate. With --json, raw state.json.

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 with step, approver identity, and timestamp, later embedded in receipt.json.

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.

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 or approver judgment quality, or business-impact conclusions
• expose internal-only proof implementation detail beyond operator and reviewer-visible artifacts

Operator and reviewer crosslinks

Operator lane

1. New Operator
2. Runbooks
3. Is This In Scope?
4. What Evidence Is Required?
5. Sensitive Artifact Handling

Approver and reviewer lane

1. Manager / Approver
2. Receipts
3. How to Verify a Receipt
4. Receipt Spec
5. Threat Model

Next-page handoff

For the separate runbook and receipt artifacts, read Proof Artifact Classes. For the app CLI's sign-in path, return to CLI setup and authentication.