# CLI Command Reference Comprehensive syntax, parameters, flags, and behaviors for every dynocap command. HTML: https://dynocap.dev/docs/reference/cli/commands Every exposed command, its output, and whether it accepts `--json`. | Command | Group | Stdout on success | `--json` | Contract | | ------------------------- | -------- | ------------------------------------------ | -------- | ------------------------------------------------ | | `dynocap runtime prepare` | primary | Preparation result | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap clone` | primary | Creation result | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap ls` | primary | Sandbox and result listing | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap doctor` | primary | Diagnostic report | yes | [Troubleshoot](/how-to/troubleshoot-with-doctor) | | `dynocap logs` | primary | Replayed streams, or `--list` discovery | no | Content stream | | `dynocap inspect` | primary | Inspection | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap exec` | primary | Guest stdout | no | Content stream | | `dynocap shell` | primary | Guest terminal | no | Interactive terminal | | `dynocap diff` | primary | Patch bytes | no | Content stream | | `dynocap finish` | primary | Finish result | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap rm` | primary | Removal result | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap run` | advanced | Raw sandbox creation result | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap ps` | advanced | `ls` listing limited to raw sandboxes | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap destroy` | advanced | `rm` removal result | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap daemon` | advanced | None; runs in the foreground until stopped | no | Foreground process | | `dynocap task start` | advanced | `clone` creation result | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap task exec` | advanced | Guest stdout, as `exec` | no | Content stream | | `dynocap task finish` | advanced | `finish` result | yes | [JSON Schemas](json-schemas.mdx) | | `dynocap version` | advanced | Version and virtualization support | yes | CLI version string / JSON | | `dynocap help` | advanced | Help text | no | Text only | --- ## Primary Workflow Commands ### `dynocap clone` Import a local project directory or Git URL into an isolated sandbox. ```sh dynocap clone SOURCE NAME [options] ``` - **Arguments:** - `SOURCE`: Path to a local directory / Git checkout, or an HTTPS/SSH Git repository URL. - `NAME`: Friendly name for the sandbox (e.g. `agent-fix`, `demo`). - **Options:** - `--runtime `: Runtime the sandbox uses. For a local directory, the default comes from its files: `package.json` → `node:24`; `pyproject.toml`, `uv.lock`, `requirements.txt`, `setup.py`, or `Pipfile` → `python:3.14`; `go.mod` → `go:1.27`. `clone` prints the runtime it chose. Otherwise, and for repository URLs, the default is `shell:1` (bash, git and ssh). The MCP server and SDK follow the same rule when `runtimes` is omitted. - `--network `: Outbound network policy. Default: `none`. - `--ttl `: Maximum lifetime from creation (30s to 86400s). Default: `1800` (30m). - `--cpus `: Number of virtual CPUs. Default: `2`. - `--memory `: RAM in megabytes. Default: `1024`. - `--history `: Git history a local directory brings in. `branches` (the default) keeps local branches, tags and remote-tracking refs; `head` keeps only the checked-out commit's history; `none` imports files only. The stash, reflogs, `refs/original`, other worktrees, submodule repositories and unreachable objects are never imported. A repository URL rejects this flag. - `--json`: Output creation object to stdout as JSON. --- ### `dynocap exec` Execute a command inside a running sandbox. ```sh dynocap exec NAME [options] -- COMMAND [args...] ``` - **Arguments:** - `NAME`: Friendly name or immutable task ID (`task-…`). - `-- COMMAND`: Command and arguments to execute inside the guest. - **Options:** - `--timeout `: Execution deadline. Default: `60`. Exceeding exits with `124`. - `-t`, `--tty`: Allocate a guest pseudo-terminal (PTY) combining stdout and stderr. - `--cwd `: Working directory inside guest. Default: `/workspace` (project) or `/` (raw). - `--env `: Set guest environment variable (repeatable). - `-i`, `--interactive`: Keep standard input open for interactive input until EOF. - `--no-input`: Send immediate EOF to guest stdin. --- ### `dynocap shell` Open an interactive `/bin/sh` shell in a running sandbox. ```sh dynocap shell NAME ``` - **Behavior:** - Requires an interactive terminal on the host. - Inherits terminal window dimensions and forwards `SIGWINCH` resize events. - Has no command timeout; session stays open until `exit` or sandbox TTL expires. - Exiting the shell leaves the sandbox running. --- ### `dynocap diff` Output a unified Git diff of all changes made in `/workspace` since creation. ```sh dynocap diff NAME ``` - **Output:** Streams clean, standard unified diff bytes (`diff --git ...`) directly to `stdout`. - **Note:** Does not alter, stop, or finish the running sandbox. --- ### `dynocap finish` Export verified patch and command logs to the host, and destroy the guest microVM. ```sh dynocap finish NAME [options] ``` - **Options:** - `--json`: Output finish result object as JSON. - **Behavior:** - Closes command admission immediately. - Exports `changes.patch`, full changed files, and execution journals into the host result directory. - Destroys the virtual machine and its disposable disk. - Prints shell-quoted `git apply` instructions. - Retains exported results on the host for 7 days from creation. --- ### `dynocap logs` Inspect or replay recorded execution output from project tasks. ```sh dynocap logs NAME [options] ``` - **Options:** - `--list`: Print a table of all recorded command executions for this task. - `--exec `: Replay stdout and stderr of a specific zero-based execution index. - **Default:** Replays stdout and stderr of the most recent execution. --- ### `dynocap ls` List active sandboxes and retained task results. ```sh dynocap ls [options] ``` - **Options:** - `--json`: Output listing array as JSON. - **Output Columns:** - `NAME/ID`: Friendly name or immutable ID. - `KIND`: `task` (project task) or `sandbox` (raw). - `PHASE`: `booting`, `running`, `stopping`, `stopped`, `completed`, or `failed`. - `RUNTIME`: Runtime identifier (e.g. `node:24` or `minimal`). - `NETWORK`: `none`, `filtered`, or `nat`. - `TTL`: Remaining time until sandbox expiration. - `RETENTION`: Remaining time until retained host results expire (7 days from creation). --- ### `dynocap inspect` Display full metadata for an active or retained task. ```sh dynocap inspect NAME_OR_ID [options] ``` - **Options:** - `--json`: Output complete inspection object as JSON. --- ### `dynocap rm` Release a sandbox name or purge retained results. ```sh dynocap rm NAME_OR_ID [options] ``` - **Options:** - `--force`, `-f`: Required to remove a sandbox that is still running or finalizing. - `--purge`: Deletes the managed task record, execution logs, and published result directory. - `--json`: Output removal result object as JSON. --- ### `dynocap doctor` Check that this Mac can run sandboxes. Each failed check says what is wrong and what to run next. Without `--fix`, doctor changes nothing. ```sh dynocap doctor [PROJECT] [options] ``` The runtime checked is the one `PROJECT` (default: the current directory) uses, judged by its files as `clone` does. With no project, no runtime is required. - **Options:** - `--fix`: Repair failed checks, then check again. Restarts a daemon from an older build (never one with running sandboxes), builds the guest image, and prepares the runtime. Builds need the dynocap checkout and Go. - `--runtime `: Check this runtime instead of the project's (`node:24`, `node:22`, `python:3.14`, `go:1.27`, `shell:1`). - `--json`: Output diagnostic report as JSON. --- ### `dynocap runtime prepare` Download, build, and verify a runtime rootfs disk. ```sh dynocap runtime prepare [REPO_PATH] [options] ``` - **Arguments:** - `REPO_PATH`: Path to the `dynocap` source tree (defaults to `.`). - **Options:** - `--runtime `: Runtime to prepare. Default `shell:1`. Supported: `node:24` and `node:22` (npm), `python:3.14` (uv), `go:1.27` (Go modules), and `shell:1` (bash, git and ssh; no language). An unsupported selection fails and lists the supported ones; no version is substituted. - `--json`: Output preparation result object as JSON. --- ## Advanced & Raw Sandbox Commands ### `dynocap run` Boot an ephemeral raw Linux microVM without a project workspace. ```sh dynocap run [options] ``` - **Options:** - `--name `: Assign a friendly name. - `--network `: Network mode. Default: `none`. - `--ttl `: Lifetime in seconds. Default: `1800`. - `--cpus `: Number of vCPUs. Default: `1`. - `--memory `: Memory in megabytes. Default: `1024`. - `--json`: Output JSON creation result. --- ### `dynocap ps` List only raw sandboxes (`kind == sandbox`). Supports `--json`. ```sh dynocap ps [options] ``` --- ### `dynocap destroy` Alias for `dynocap rm` without `--purge`. Requires `--force` for running sandboxes. ```sh dynocap destroy NAME_OR_ID [--force] ``` --- ### `dynocap daemon` Run the DynoCap background daemon in the foreground. ```sh dynocap daemon [options] ``` - Emits daemon logs directly to stdout/stderr. Used primarily for debugging daemon lifecycle.