--- title: "vakna fork" description: "Fork a box n times from a snapshot and run a command in each." command: "vakna fork" generated: scripts/generate.ts verified: cli: "0.0.0-mock" date: "2026-10-20" --- `vakna fork`: fork a box n times from a snapshot and run a command in each. Proposed: the real CLI doesn't have this command yet. ## Synopsis ```sh vakna fork --count -- ``` ## Flags | Flag | Default | What it does | | -- | -- | -- | | `--count ` | `1` | boxes to fork, up to 1000 | | `--name ` | `fork-` | the task's name, shown on its receipt | | `--format ` | `text` | text, or json: one JSON object per line | | `--json` | `off` | the same as --format json | | `-h, --help` | `off` | this help | ## Examples ### Example ```sh $ vakna fork api --count 50 -- go test -run TestRetry ./retry/... ``` ```prints snapshot snp_eu1a_z7a8b9c0 taken 0.19s forked api ×50 from snapshot · 0.34s each task prove-flaky-retry tsk_eu1a_0k1m2n3p ran go test -run TestRetry ./retry/... in 50 boxes · 42 exit 0, 8 failed 2m 11s errors: 2 signatures assertion in retry_test.go:88 ×6 timeout after 30s ×2 receipt: prove-flaky-retry · 50 boxes · 8 failed · 2m 11s · $0.46 · mocked ``` Exit code 1. ### Another example ```sh $ vakna fork api --count 1000 --name prove-hypothesis-42 -- pytest -k slow ``` ```prints snapshot snp_eu1a_z7a8b9c0 taken 0.19s forked api ×1,000 from snapshot · 0.34s each task prove-hypothesis-42 tsk_eu1a_4x5y6z7a ran pytest -k slow in 1,000 boxes · 994 exit 0, 6 failed 3m 20s errors: 3 signatures OOM in test runner ×3 port 5432 already in use ×2 timeout after 45s ×1 receipt: prove-hypothesis-42 · 1,000 boxes · 6 failed · 3m 20s · $4.12 · mocked ``` Exit code 1. ### When it fails ```sh $ vakna fork api --count 5000 -- go test ./... ``` ```prints vakna: --count 5,000 is over the limit of 1,000 boxes per task hint: vakna fork --help # split it into tasks of 1,000 or fewer ``` Exit code 255. ## Exit codes | Code | Meaning | | -- | -- | | 0 | ok | | 1 | vakna failed; under shell, run, try or fork, the command in the box failed | | 2 | usage: a missing argument, an unknown flag or command | | 255 | vakna failed under shell, run, try or fork | ## JSON output With `--format json` (or `--json`) every line is one JSON object. `v` is the format's version; `mocked` marks numbers from the mock. ```sh $ vakna fork api --count 50 --json -- go test -run TestRetry ./retry/... ``` ```prints {"v":1,"event":"snapshot","box":"api","id":"sbx_eu1a_01JB7X9K3M4N5P6Q7R8S9T0V1W","snapshot":"snp_eu1a_01JB83S1T2V3W4X5Y6Z7A8B9C0","ms":190,"mocked":true} {"v":1,"event":"forked","box":"api","snapshot":"snp_eu1a_01JB83S1T2V3W4X5Y6Z7A8B9C0","count":50,"eachMs":341,"mocked":true} {"v":1,"event":"task","id":"tsk_eu1a_01JB7Y4D5E6F7G8H9J0K1M2N3P","name":"prove-flaky-retry","mocked":true} {"v":1,"event":"ran","task":"tsk_eu1a_01JB7Y4D5E6F7G8H9J0K1M2N3P","command":"go test -run TestRetry ./retry/...","boxes":50,"exit0":42,"failed":8,"ms":131000,"mocked":true} {"v":1,"event":"errors","task":"tsk_eu1a_01JB7Y4D5E6F7G8H9J0K1M2N3P","signatures":[{"signature":"e3b0c442","label":"assertion in retry_test.go:88","count":6},{"signature":"9f86d081","label":"timeout after 30s","count":2}],"mocked":true} {"v":1,"event":"receipt","receipt":{"kind":"task","id":"tsk_eu1a_01JB7Y4D5E6F7G8H9J0K1M2N3P","name":"prove-flaky-retry","startedAt":"2026-10-17T11:20:00Z","endedAt":"2026-10-17T11:22:11Z","boxes":50,"coldBoots":0,"forks":50,"forkEachMs":341,"medianReadyMs":346,"wallClockMs":4700000,"elapsedMs":131000,"suspendedMs":0,"passed":42,"failures":[{"signature":"e3b0c442","label":"assertion in retry_test.go:88","count":6},{"signature":"9f86d081","label":"timeout after 30s","count":2}],"costMicros":456944,"trial":false,"mocked":true},"mocked":true} ``` ## Errors - [`vakna: unknown command, unknown flag or missing argument`](https://vakna.com/docs/errors/usage): Run `vakna --help` and fix the command line it points to. - [`vakna: no box ""`](https://vakna.com/docs/errors/not_found): Run `vakna list` and use a name from it. - [`vakna: "" matches more than one box`](https://vakna.com/docs/errors/ambiguous): Use the box's name or its full id; `vakna list` shows both. - [`vakna: box is suspended`](https://vakna.com/docs/errors/suspended): Run `vakna resume `, then run your command again. - [`vakna: --count is over the limit of 1,000 boxes per task`](https://vakna.com/docs/errors/fork_limit): Split the work into tasks of 1,000 boxes or fewer, one `vakna fork` each. ## --help This page and the help text come from one definition. ```prints vakna fork · fork a box n times from a snapshot and run a command in each Proposed: the real CLI doesn't have this command yet. usage vakna fork --count -- flags --count boxes to fork, up to 1000 (default: 1) --name the task's name, shown on its receipt (default: fork-) --format text, or json: one JSON object per line (default: text) --json the same as --format json (default: off) -h, --help this help (default: off) examples vakna fork api --count 50 -- go test -run TestRetry ./retry/... vakna fork api --count 1000 --name prove-hypothesis-42 -- pytest -k slow exit codes 0 ok 1 vakna failed; under shell, run, try or fork, the command in the box failed 2 usage: a missing argument, an unknown flag or command 255 vakna failed under shell, run, try or fork ```