CLI Error Contracts

When a command fails, dynocap sends error details to stderr and preserves standard output.

JSON Error Envelope

When --json is used on a management command, any validation or operational failure prints exactly one JSON object to stderr followed by a newline:

JSON

{
  "error": {
    "code": "live_sandbox_refusal",
    "message": "sandbox 'demo' is running; unexported changes would be lost",
    "recovery": "Export with 'dynocap finish demo' or discard with 'dynocap rm demo --force'.",
    "exitCode": 1
  }
}

stdout remains completely empty.
The process terminates with the numeric exitCode specified in the envelope.

Human Error Format

Without --json, failures write clean, human-readable diagnostics to stderr without stack traces or global help dumps:

Text

dynocap: rm: sandbox 'demo' is running; unexported changes would be lost
Next: Export with 'dynocap finish demo' or discard with 'dynocap rm demo --force'.

Standard Error Codes

Error Code	Exit Code	Description
`invalid_usage`	`2`	Unknown flag, invalid argument combination, or missing required parameter.
`not_found`	`1`	Specified sandbox, task ID, or result directory does not exist or has expired.
`already_exists`	`1`	A sandbox or task already exists with the requested friendly name.
`live_sandbox_refusal`	`1`	Attempted to delete an active sandbox without `--force`.
`command_timeout`	`124`	Guest command exceeded `--timeout` deadline.
`daemon_unreachable`	`1`	Unable to connect to `~/.dynocap/daemon.sock` after startup timeout.
`unsupported_platform`	`1`	Running on unsupported OS (non-macOS) or unsupported architecture.
`entitlement_missing`	`1`	Binary lacks `com.apple.security.virtualization` code signature.
`runtime_not_prepared`	`1`	Requested runtime rootfs has not been prepared with `runtime prepare`.
`network_policy_violation`	`1`	Outbound request blocked by egress policy or restricted host flags.

This page is also plain Markdown, for agents and for you.