reference developer public

CLI reference

The DRC CLI is the shortest path from a local application to replayable evidence and service-level Signal runs. Install it through npm as described in Install DRC. Customer workflows use the installed drc binary directly. Run drc --help or drc <command> --help for the complete, current flag list for your version; this page explains what each command is for.

Global rules

Human output is the default and is intentionally compact.
Use --json for scripts, CI, and agents. drc search and drc diff also accept --format json|table; every command that reports data accepts --json.
Stdout carries command output and JSON only. Diagnostics and log records go to stderr, so a piped document is never mixed with log lines.
A failed operation returns a non-zero exit code. Exit codes are stable: 1 general, 2 configuration, 3 authentication, 5 network, 6 validation (including an execution ID no storage root holds), 9 replay, 11 proxy, 12 MCP, 13 policy gate blocked.
Captures are discoverable from any working directory: drc search and the execution commands find an execution captured by another project on the same machine. DRC_STORAGE_PATH targets one specific root when set, and DRC_HOME relocates DRC's per-user state directory (default ~/.drc).
IDs are stable handles; do not infer state from display formatting.

Commands

Account and access

Command	Use
`drc init [codebase]`	Initialize capture configuration for a codebase root silently on success. Writes the service identity and default-enabled telemetry policy into `.drc/drc.toml`; use `--service <name>` to name the service. Product telemetry privacy is controlled from the hosted account, not by an init flag. Safe to rerun; `--force` replaces an existing configuration.
`drc login`	Sign in to a DRC API server and store a local token. Create hosted accounts through the web signup flow.
`drc logout`	Remove the stored login token.
`drc whoami`	Show the signed-in identity without printing secrets.
`drc diagnose [--json]`	Check local CLI prerequisites and settings. Exits non-zero when a setting cannot work (for example an empty or malformed `DRC_AUTH_TOKEN`, or a non-HTTP `DRC_API_URL`); a missing storage directory is reported as a warning only. Aliases: `doctor`, `check`.
`drc healthcheck --url <url>`	Check an HTTP health endpoint and exit non-zero when it is unhealthy.
`drc api-key` (`generate`, `revoke`, `list`)	Create, revoke, and list service-account keys. Only key hashes are stored; pass `--file` for the durable record.
`drc mcp`	Expose the local analysis engine over the Model Context Protocol for MCP clients such as Claude Code or Cursor.

Capture

Command	Use
`drc run`	Start the capture daemon in the background. Proxies traffic sent to its configured listener from `--port` to `--target-port`; repeat `--extra-port` to add explicit target ports. This proxy mode does not discover or intercept every port. Optionally starts an app subprocess with `--app-command`. On supported Linux installations, `--all-ports --app-command <cmd>` starts the app inside an isolated cgroup and passively captures supported TCP/UDP packet metadata with eBPF. It does not redirect traffic or capture payloads, and reports unsupported packets and capture loss in a summary event. Your Linux administrator or container runtime must provide `DRC_CAPTURE_CGROUP_ROOT`, a writable cgroup v2 directory where DRC may create a child group and start the app. Cgroup namespaces that block moving a process into that group are unsupported. DRC checks the supplied path before daemon startup; the OS may still reject app launch when process migration is restricted. This option is available only in Linux builds that include all-ports support; macOS and other builds reject it.
`drc watch`	Stream events live from a running daemon. Use `--filter` to narrow by substring and `--project-dir <path>` to select a daemon started for another project.
`drc stop`	Gracefully stop the daemon; buffered events are flushed and finalized before exit. Use `--project-dir <path>` to select a daemon started for another project. `--force` kills immediately and may abandon buffered data.
`drc capture`	Run a foreground, explicitly routed HTTP proxy and persist bounded request/response events to local storage until Ctrl-C. Use `--target-host`/`--target-port` for the app, `--service`, `--output`, repeatable `--tag`, and opt-in `--capture-bodies`. HTTPS interception and process-wide capture are not provided. On Windows, this is the primary capture workflow; on Unix, this is a foreground explicit HTTP proxy while `drc run` is the background daemon with proxy/eBPF capture.
`drc capture --pid <pid>`	Attach a kernel tracer to one running process and persist each syscall it completes (name, thread, arguments, return value, errno, duration, and the resolved path for `open`/`openat`) in bounded batches until the process exits or Ctrl-C; stopping detaches without pausing or killing the target. This observes the attached process and the descendants the tracer reports, not the whole host, and it requires Linux 5.3 or newer with `kernel.yama.ptrace_scope` permitting the attach (root or `CAP_SYS_PTRACE` when the scope is restricted), or macOS with a usable dtrace provider. The resulting execution is finalized as partial.
`drc search`	List captured executions. Filter with `--service`, `--time-range`, and `--state`; use `--format table`, `--format json`, or `--json`. Alias: `ls`.
`drc import`	Import telemetry from external systems. Subcommands: `datadog`, `splunk`. Write results with `--output <root>` (default `.drc/storage`). Credentials can come from `DD_API_KEY`/`DD_APP_KEY` or `SPLUNK_TOKEN` instead of flags so they stay out of shell history.

Investigate

Command	Use
`drc trace <id-or-window>`	Show the causal chain of an execution: events, dependencies, and errors traced back to root cause.
`drc analyze --execution-id <id>` or `drc analyze <window>`	Summarize one capture or every failing capture in a time window; these modes do not claim to detect divergence.
`drc analyze --baseline <id> --candidate <id> [--json]`	Compare recorded event streams in event order, report differences and (when stream lengths align) seven-layer divergence analysis. Capture timestamps are ignored. Does not execute application code.
`drc replay --execution-id <id>` or `drc replay <window>`	Replay an execution strictly. Modes: `strict`, `adaptive`, `mutated`, `approximate`. Apply a fix spec with `--fix` or a mutation with `--mutation`. Alias: `replay-exec`.
`drc diff <baseline> <candidate>`	Compare two executions and identify the earliest divergence. Use `--format json` (default), `--format table`, or `--json`. Alias: `compare`.
`drc bisect --baseline <id> --mutated <id>`	Binary-search events to find the minimal set that produces an error.
`drc blast-radius --execution-id <id>`	Scan all executions for the bug pattern found in a reference execution and show aggregate impact.
`drc fix [id-or-window]`	Confirm a fixed codebase resolves captured failures. `--dir` points at the fixed tree; defaults to the project root.
`drc counterfactual --execution-id <id> --modifications <file>`	Run what-if modifications against a captured execution and report which paths stay identical versus diverge.
`drc inject --execution-id <id> --injections <file>`	Apply virtualized state changes (clock, files, environment, DB, cache) to an execution. Alias: `inject-state`.
`drc chaos --execution-id <id> --spec <file>`	Apply chaos mutations across all virtualization layers. Alias: `layer-mutate`.
`drc regress --execution-id <id> --test-config <file>`	Promote a captured execution into a regression test and run it. Alias: `execution-as-test`.
`drc reproduce --execution-id <id> --command <file> --language <language>`	Generate a runnable isolated-replay regression test from a captured execution. The command file must contain a valid `ReplayCommand`; execution requires Linux, Bubblewrap, and `DRC_REPLAY_ROOTFS`. Languages: `rust`, `node`, `python`, `go`.
`drc mutate` (`create`, `validate`, `list`)	Create, validate, and list mutation specs used during replay.
`drc privacy audit <capture>`	Scan JSON object field names for terms from the policy and report likely raw sensitive fields. This is a heuristic audit only: it does not apply redaction or establish that a capture is safe. `--fail-on-leak` exits non-zero when a matching field value is not already masked.

Command	Use
`drc push --execution-id <id>` / `drc pull --execution-id <id>`	Upload an execution to the hosted registry or download one. The captured service, environment, version, and tags are preserved; local delivery adds `source:cli-push`. Use `--target` / `--source` to use a local storage root instead. Aliases: `upload`, `download`.
`drc share --execution-id <id> --recipient <email>` / `drc unshare --execution-id <id> --recipient <email>` / `drc shares list`	Share an execution with another DRC user, revoke a share, or list executions shared with you. `--recipient` is required because a share is always addressed to a specific person.
`drc incident export --execution-id <id>`	Produce a portable incident packet for handoff.

Verification and deployment

Command	Use
`drc signal`	Read Signal cloud verification workflow configuration and recent run status in HyperCubs.
`drc signal <service>`	Read HyperCubs cloud verification status with recent runs filtered to a service.
`drc signal --history [<service>]`	Read recent CV run status from HyperCubs cloud verification, optionally filtered by service.
`drc signal cc ...`	HyperCubs-hosted Continuous Compliance operations: `check`, `run`, `status`, `history`, `show`, `sync`, `frameworks`, `controls`.
`drc signal cc` (`status`, `controls`, `sync`)	Read and reconcile CC state in HyperCubs.
`drc gateway check --baseline <id> --candidate <id> --deployment-id <id>`	Verify a deployment against baseline and candidate executions. `--block-on-forecast` is a legacy flag name for blocking when novel candidate error patterns in the shared corpus recommend review; it does not request a forecast.
`drc gate evaluate`	Evaluate a candidate change against policy rules from the Evidence Control Plane.

Operator (self-managed deployments)

Command Use

drc server (start, status, stop, migrate, worker) start runs the API server in the foreground and records its PID under .drc/server.pid in the selected project directory; its ephemeral runtime state defaults to /var/lib/drc/runtime and is overridable with DRC_SERVER_RUNTIME_DIR. status checks that process identity; stop sends SIGTERM and waits up to 30 seconds for graceful shutdown. Use the same --project-dir for all three commands. worker runs the dedicated hosted worker; migrate runs hosted migrations under the migration process role.

Command	Use
`drc server` (`start`, `status`, `stop`, `migrate`, `worker`)	`start` runs the API server in the foreground and records its PID under `.drc/server.pid` in the selected project directory; its ephemeral runtime state defaults to `/var/lib/drc/runtime` and is overridable with `DRC_SERVER_RUNTIME_DIR`. `status` checks that process identity; `stop` sends SIGTERM and waits up to 30 seconds for graceful shutdown. Use the same `--project-dir` for all three commands. `worker` runs the dedicated hosted worker; `migrate` runs hosted migrations under the migration process role.

Continuous Compliance contracts

CC is separate from CV even though both are configured in .drc/signal.yml. Use the shared Signal command with the compliance subcommands:


drc signal cc frameworks
drc signal cc controls
drc signal cc status
drc signal cc history
drc signal cc show <evaluation-id>

Framework and control discovery reports the pinned version, technical-subset disclaimer, selected/evaluated counts, supported detector, required evidence, exact checks, and whether the control is included or requires a paid CC add-on. Unsupported controls are rejected by signal check and cannot run.

CC results expose only compliant or non_compliant. Detailed results include expected policy, observed values, evidence links, remediation, evaluator version, manifest hash, evaluated commit, environment, and blocker codes. The service-level wording is: "This service passed the selected machine-evaluable technical controls in the configured framework profile."

Examples


drc init --service checkout-api
drc run --port 8080 --target-port 3000
# Start or inspect the hosted API process for this project
drc server start --project-dir .
drc server status --project-dir .
drc server stop --project-dir .
# Linux only, when the administrator/runtime provides a writable cgroup v2 directory:
# DRC_CAPTURE_CGROUP_ROOT=/path/provided/by-your-linux-admin drc run --all-ports --app-command "npm start"
# Add explicit listeners for other target ports
drc run --port 8080 --target-port 3000 --extra-port 5432 --extra-port 6379
drc watch
drc stop
drc search --format table
drc search --format json
drc replay --execution-id exec_abc123 --json
drc diff exec_baseline exec_candidate --format json
drc signal
drc signal checkout
drc signal --history checkout
drc signal cc status

Signal

Signal is the cloud verification workflow for Continuous Verification and Continuous Compliance in HyperCubs. Configure connected repository workflows and review their status, logs, and history on the HyperCubs website. The CLI provides authenticated access to workflow state. .drc/signal.yml remains available for declarative compliance policy/configuration sync where supported. Read Continuous Verification, Continuous Compliance, and Signal YAML reference.


# Read Signal cloud verification workflows and recent run status in HyperCubs
drc signal

# Filter recent cloud runs by service (all connected workflows remain listed)
drc signal checkout

# Read CV run history, optionally filtered by service
drc signal --history
drc signal --history checkout

# Read CC state in HyperCubs
drc signal cc status
drc signal cc controls

drc signal fetches tenant-scoped workflow and recent run information from the HyperCubs cloud verification workflow using the signed-in account. Use the HyperCubs website for full workflow configuration, logs, and history.

The CC branch is separate: drc signal cc status and controls read hosted compliance control/evaluation state. CC evaluates the configured service independently. Its precise user-facing result is either compliant or non_compliant: "This service passed the selected machine-evaluable technical controls in the configured framework profile."

The shared file supports services.<name>.cc declarations for compliance policy/configuration sync. CV workflows are configured and run through HyperCubs cloud verification; DRC evidence and compliance records remain tenant-scoped and immutable.

Output contract

Human replay output reports the execution ID, mode, storage authority, events loaded, validation result, and events replayed. JSON includes machine-readable status and error fields. Zero events or an incomplete validation is not reported as a successful replay.

Log records are written to stderr. drc run prints its confirmation only after the daemon reports that it is capturing, and exits non-zero (with the tail of .drc/daemon.log) when the daemon fails during startup.

Time-window mode

Analysis commands can operate on a time window instead of one selected execution. Use a duration such as 24h, 7d, 30d, or 6mo as the positional target:


drc search 24h
drc trace 24h --limit 20
drc analyze 30d --limit 50          # summarize each failing capture
# Compare two captures; different capture timestamps are ignored:
drc analyze --baseline exec_before --candidate exec_after --json
drc replay 6mo --limit 20

Window mode finds executions started in the window that contain an error or exception, processes them newest first, and caps the result at --limit. It returns one result per execution. Use --execution-id <id> when you want exactly one execution; an explicit ID and a time window cannot be supplied together. Commands that resolve a single target, such as drc fix 30d, use the newest matching failure rather than iterating every failure.

MCP clients use the equivalent since and limit arguments on trace, analyze, and replay. CLI baseline/candidate comparison is explicit with drc analyze --baseline <id> --candidate <id>; JSON reports set comparison_performed and include the actual stream differences.

Watch subcommands

Watching unfiltered traffic is intentionally not the default workflow. Use a scoped watch mode for an investigation or a bounded port capture, and stop it when the diagnostic window ends. Long-running observation should be configured with retention and redaction policy before it starts.

Initialization metadata

drc init records runtime = "port-runtime" and treats language as optional metadata. The universal-proxy path is selected from observed ports rather than a required language field. Multi-datacenter deployments can declare datacenter and replication-factor values; the replication factor cannot exceed the datacenter count. Initialization is safe to rerun, and --force is required before replacing an existing configuration.

Failure output

Validation failures return a non-zero exit code and identify the operation. Mutation validation and hosted Continuous Compliance commands reject malformed or unsupported requests.

Configuration

There is no drc config subcommand in the current CLI. Use Configuration reference for environment settings and inspect .drc/drc.toml for local capture configuration. See drc whoami for the signed-in identity; it does not print tokens.