# Workspace Runs (/docs/cli/workspace-runs)



The Workspace Run CLI commands drive the archive-based workflow: create a run,
upload an existing `.tar.gz` or `.tgz`, start execution, stream output,
and download evidence.

Use `run-archive` to do all of that in one command. It uploads the archive,
runs the remote command, streams stdout and stderr, and exits with the remote
command's exit code. After the command reaches a terminal state, read the
Evidence Bundle as the durable terminal proof for archive checksum, timing,
exit code, artifact IDs, and failure details. Use `logs` or `--json` event
replay for stdout and stderr.

## One command [#one-command]

```bash title="Terminal"
crownest workspace-runs run-archive repo.tgz --template python-node -- pnpm test
```

The CLI uploads the archive, starts the run, streams output, and exits with
the run command's exit code.

Write the terminal proof after completion:

```bash title="Terminal"
crownest workspace-runs evidence wsr_abc123 --output evidence.json
```

Use `--json` to print each stream event as a JSON envelope:

```bash title="Terminal"
crownest workspace-runs run-archive repo.tgz --json -- pytest -q
```

<Callout type="info" title="Archive size">
  The CLI uses staged archive transfer, so repo archives can use the larger Workspace
  Run transfer limit. The low 8 MiB cap applies only to direct API upload.
</Callout>

## Step-by-step flow [#step-by-step-flow]

Create a run:

```bash title="Terminal"
crownest workspace-runs create \
  --template python-node \
  --command "pnpm test" \
  --metadata repo=acme/app
```

Upload an existing archive:

```bash title="Terminal"
crownest workspace-runs upload wsr_abc123 repo.tgz
```

Start it:

```bash title="Terminal"
crownest workspace-runs start wsr_abc123
```

Stream events:

```bash title="Terminal"
crownest workspace-runs logs wsr_abc123
```

Read status:

```bash title="Terminal"
crownest workspace-runs status wsr_abc123 --json | jq .data.exitCode
```

Write evidence after completion:

```bash title="Terminal"
crownest workspace-runs evidence wsr_abc123 --output evidence.json
```

Cancel an active run:

```bash title="Terminal"
crownest workspace-runs cancel wsr_abc123
```

## Commands [#commands]

### crownest workspace-runs create [#crownest-workspace-runs-create]

Create a Workspace Run record.

```bash
crownest workspace-runs create --command <command> [--project <prj_id>] [--template <slug>] [--sandbox <sbx_id>] [--keep-sandbox] [--timeout-ms <ms>] [--metadata key=value]... [--json]
```

| Flag             | Description                                        |
| ---------------- | -------------------------------------------------- |
| `--command`      | Shell command to run after archive extraction.     |
| `--project`      | Project to create the run in.                      |
| `--template`     | CrowNest template slug, for example `python-node`. |
| `--sandbox`      | Warm sandbox to reuse.                             |
| `--keep-sandbox` | Keep the sandbox after the run.                    |
| `--timeout-ms`   | Command timeout in milliseconds.                   |
| `--metadata`     | Metadata label as `key=value`. Repeatable.         |
| `--json`         | Print `{ "data": ... }`.                           |

### crownest workspace-runs upload [#crownest-workspace-runs-upload]

Upload an existing archive to a run.

```bash
crownest workspace-runs upload <workspace-run-id> <archive.tgz> [--sha256 <hex>] [--json]
```

`archive.tgz` must be a file ending in `.tgz` or `.tar.gz`. Directories are
rejected. The CLI hashes and uploads the archive as a file stream.

### crownest workspace-runs start [#crownest-workspace-runs-start]

Start extraction and command execution.

```bash
crownest workspace-runs start <workspace-run-id> [--json]
```

### crownest workspace-runs run-archive [#crownest-workspace-runs-run-archive]

Create a run, upload an existing archive, start it, and stream events.

```bash
crownest workspace-runs run-archive <archive.tgz> [--project <prj_id>] [--template <slug>] [--sandbox <sbx_id>] [--keep-sandbox] [--timeout-ms <ms>] [--metadata key=value]... [--json] -- <command>
```

Everything after `--` becomes the command line. The CLI exits with the
remote command's exit code when the run reaches a terminal event.

### crownest workspace-runs status [#crownest-workspace-runs-status]

Retrieve current run status.

```bash
crownest workspace-runs status <workspace-run-id> [--json]
```

### crownest workspace-runs list [#crownest-workspace-runs-list]

List Workspace Runs.

```bash
crownest workspace-runs list [--project <prj_id>] [--status <status>] [--json]
```

### crownest workspace-runs logs [#crownest-workspace-runs-logs]

Stream Workspace Run events. Use `--after-seq` to resume after a known
event sequence.

```bash
crownest workspace-runs logs <workspace-run-id> [--after-seq <n>] [--json]
```

Without `--json`, stdout events are written to stdout and stderr events are
written to stderr. With `--json`, each event is printed as
`{ "data": ... }`.

### crownest workspace-runs cancel [#crownest-workspace-runs-cancel]

Cancel an active run. Canceling a terminal run returns its current state.

```bash
crownest workspace-runs cancel <workspace-run-id> [--json]
```

### crownest workspace-runs evidence [#crownest-workspace-runs-evidence]

Read the durable Evidence Bundle. Use `--output` to write pretty JSON to a
file.

```bash
crownest workspace-runs evidence <workspace-run-id> [--output <path>] [--json]
```

## Dashboard inspection [#dashboard-inspection]

After a CLI-created Workspace Run starts, the signed-in dashboard can inspect
it at `/workspace-runs`. The dashboard shows status, command, template, timing,
exit code, Artifact IDs, and Evidence Bundle fields, and it can cancel active
runs.

Use the CLI, API, SDK, or Crabbox to create and start runs.

## Next steps [#next-steps]

* [API Workspace Runs](/docs/api/workspace-runs) — endpoint details.
* [TypeScript SDK Workspace Runs](/docs/sdk/workspace-runs) — typed client
  helpers.
* [Command reference](/docs/cli/commands) — every CLI command.