# CLI JSON Schemas

Exact JSON schemas and field definitions for scripting and automated integration with the dynocap CLI.

HTML: https://dynocap.dev/docs/reference/cli/json-schemas

When passed `--json`, management commands print a single line-delimited JSON payload to `stdout`. Absent values are explicitly represented as `null`, timestamps are integer Unix epoch seconds (UTC), and consumers must tolerate extra fields.

---

## 1. Listing Schema (`dynocap ls --json`)

Returns an array of sandbox and task records:

```json
[
  {
    "id": "task-8f92b7c1",
    "name": "demo",
    "kind": "task",
    "phase": "running",
    "runtime": "node:24",
    "network": "none",
    "sandboxExpiresAtUnix": 1794958200,
    "resultExpiresAtUnix": 1795563000,
    "resultDirectory": null
  }
]
```

### Fields

| Field                  | Type              | Description                                                                                      |
| :--------------------- | :---------------- | :----------------------------------------------------------------------------------------------- |
| `id`                   | `string`          | Immutable task ID or raw sandbox name.                                                           |
| `name`                 | `string \| null`  | Friendly name assigned at creation, or `null`.                                                   |
| `kind`                 | `string`          | `"task"` (project sandbox) or `"sandbox"` (raw).                                                 |
| `phase`                | `string`          | Lifecycle phase: `"booting"`, `"running"`, `"stopping"`, `"stopped"`, `"completed"`, `"failed"`. |
| `runtime`              | `string`          | Runtime identifier (e.g. `"node:24"`, `"minimal"`).                                              |
| `network`              | `string \| null`  | `"none"`, `"filtered"`, `"nat"`, or `null`.                                                      |
| `sandboxExpiresAtUnix` | `integer \| null` | Absolute TTL deadline in seconds. `null` if VM is stopped.                                       |
| `resultExpiresAtUnix`  | `integer \| null` | Absolute retention deadline for logs and diffs (7 days from creation).                           |
| `resultDirectory`      | `string \| null`  | Absolute path to exported host result directory, or `null`.                                      |

---

## 2. Creation Schema (`dynocap clone --json`)

Returned by `dynocap clone` and `dynocap task start`:

```json
{
  "id": "task-8f92b7c1",
  "name": "demo",
  "phase": "running",
  "runtimeDigest": "sha256:d8b2...",
  "createdAtUnix": 1794956400,
  "expiresAtUnix": 1794958200,
  "sourceUrl": null,
  "sourceRevision": "4b92c41"
}
```

---

## 3. Finish Schema (`dynocap finish --json`)

Returned when a task is finalized and exported:

```json
{
  "applyCommand": "git apply --check '/Users/user/.dynocap/tasks/task-8f92b7c1/result/changes.patch' && git apply '/Users/user/.dynocap/tasks/task-8f92b7c1/result/changes.patch'",
  "baseline": "imported_checkout_including_uncommitted_changes",
  "hostCheckout": "unchanged",
  "id": "task-8f92b7c1",
  "name": "demo",
  "patch": "/Users/user/.dynocap/tasks/task-8f92b7c1/result/changes.patch",
  "phase": "completed",
  "priorCommandFailure": false,
  "resultDirectory": "/Users/user/.dynocap/tasks/task-8f92b7c1/result",
  "resultExpiresAtUnix": 1795563000,
  "sandbox": "stopped",
  "sensitivePaths": [
    {
      "kind": "added",
      "path": ".husky/pre-commit",
      "reason": "Git hooks run on commit"
    }
  ]
}
```

`sensitivePaths` lists changes that can run code on the host or in CI once the patch is applied: Git hooks, CI workflows, editor tasks, package and build scripts, `.envrc`, symlinks, and files that become executable. It is empty when there are none. Each entry also appears in `changes.json` as `sensitive`.

---

## 4. Inspection Schema (`dynocap inspect --json`)

Returned by `dynocap inspect NAME`:

```json
{
  "id": "task-8f92b7c1",
  "name": "demo",
  "kind": "task",
  "taskPhase": "completed",
  "sandboxPhase": "stopped",
  "runtime": "node:24",
  "network": "none",
  "createdAtUnix": 1794956400,
  "sandboxExpiresAtUnix": 1794958200,
  "resultExpiresAtUnix": 1795563000,
  "resultDirectory": "/Users/user/.dynocap/tasks/task-8f92b7c1/result",
  "patchPath": "/Users/user/.dynocap/tasks/task-8f92b7c1/result/changes.patch",
  "sourcePath": "/tmp/demo-project",
  "sourceRevision": "4b92c41"
}
```

---

## 5. Removal Schema (`dynocap rm --json`)

Returned by `dynocap rm` and `dynocap destroy`:

```json
{
  "target": "demo",
  "removed": true,
  "purged": false
}
```

---

## 6. Doctor Schema (`dynocap doctor --json`)

Diagnostic report of host readiness. Findings go to stdout in both modes; the command exits 1 when a required check fails.

```json
{
  "ok": false,
  "home": "/Users/user/.dynocap",
  "arch": "aarch64",
  "runtimes": [{ "name": "node", "version": "24" }],
  "checks": [
    {
      "id": "platform",
      "status": "ok",
      "message": "macOS 13+; guest architecture aarch64",
      "recovery": null,
      "fix": null
    },
    {
      "id": "runtime",
      "status": "error",
      "message": "Runtime node:24 is not prepared for aarch64 yet.",
      "recovery": "Run dynocap doctor --fix to prepare node:24 (downloads verified inputs; takes a few minutes).",
      "fix": "prepare-runtime"
    }
  ]
}
```

- `status` is `ok`, `warning`, or `error`. Only `error` makes `ok` false.
- `runtimes` is the runtime that was checked: `--runtime`, or the one the project's files call for. It is empty when there was no project. The `runtime` check then lists the prepared runtimes and is a `warning` if there are none.
- `fix` is the repair `doctor --fix` performs for this check on this machine (`restart-daemon`, `build-images`, or `prepare-runtime`), or `null` when the check passes or needs a manual step. When it is set, `recovery` names the exact command.

With `--fix`, the report describes the state after repairs and adds `repairs`, in the order they ran:

```json
"repairs": [
  {
    "fix": "build-images",
    "status": "fixed",
    "summary": "Building the guest image for aarch64",
    "recovery": null,
    "logPath": "/Users/user/.dynocap/image-build-....log",
    "note": null,
    "seconds": 20.4
  }
]
```

`status` is `fixed`, `failed`, or `skipped`. A runtime repair is skipped when the daemon restart failed. `note` reports side effects, such as where mismatched image files were moved.