# `once exec`

Execute a literal action through the cache

## Synopsis

```text
once exec [OPTIONS] [ARGV]
```

## Description

Low-level action surface for direct commands and script adapters. The cache key is the full argv, declared environment variables, optional working directory, and optional timeout. A second invocation with the same key reuses the captured stdout, stderr, and exit code. With `--script`, or when argv looks like `<runtime> <script> [args...]` and the file has `once` headers, Once applies script-aware parsing instead.

## Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `<ARGV>` | no | Command and arguments. Use `--` to separate from once flags |

## Options

| Flag | Value | Default | Description |
| --- | --- | --- | --- |
| `--sandbox` | `<SANDBOX>` | `off` | Local filesystem sandbox policy for the command action |
| `--script` | (flag) | `false` | Interpret argv as `<runtime> <script> [args...]` and apply `once` headers from the script file. Useful as the explicit form, for example `once exec --script bash scripts/build.sh`, and for directly executable scripts via a shebang such as `#!/usr/bin/env -S once exec -- bash` |
| `-e` | `<ENV>` |  | Pass an environment variable to the command. Repeatable |
| `--cwd` | `<CWD>` |  | Working directory, relative to the project root. Must not be absolute or escape the project |
| `--timeout-ms` | `<MS>` |  | Per-action timeout in milliseconds. The child is killed if it exceeds the deadline |
| `--cache-failures` | (flag) | `false` | Cache non-zero exits the same way zero exits are cached. Off by default; transient failures shouldn't poison the cache |
| `--verify-reproducible` | (flag) | `false` | Run the action twice while bypassing the cache and report whether the two trials produced identical results, instead of executing normally. Exits non-zero when any divergence is found. Useful for catching nondeterministic tools and undeclared inputs that leak through the cache key |
| `--remote` | (flag) | `false` | Run the command on a compute provider |
| `--network` | `<NETWORK>` | `unrestricted` | Whether the command may reach the network. Defaults to `unrestricted` (the host network is available, matching existing behavior). `deny` isolates the command from the network on Linux so an undeclared fetch fails loudly instead of leaking into the cache key |
| `--compute` | `<PROVIDER>` |  | Compute provider used with --remote. Defaults to the configured execution provider |
| `-C, --directory` | `<DIR>` |  | Project root. Defaults to the current directory; the cache lives under `<project>/.once/`. Mirrors `make -C` |
| `--format` | `<FORMAT>` | `human` | Output format for Once's structured data (`cache stats`, `run`/`exec` trailers). Defaults to a human-readable rendering; pass `json` or `toon` to get machine-parseable output for scripting and for agent consumers |
| `-v, --verbose` | (flag) | `0` | Increase log verbosity. Repeat for more (-v: info, -vv: debug, -vvv: trace). Overridden by `RUST_LOG` |
| `-q, --quiet` | (flag) | `false` | Suppress human-mode success and progress trailers. Errors and the structured envelope of `--format json`/`toon` still print. Mirrors the `-q` flag of common build tools |
| `--list` | (flag) | `false` | Print the command surface at the current command depth |
| `--memory-limit` | `<SIZE>` |  | Maximum memory scheduling budget for local actions. Defaults to two thirds of the memory visible to the host or container |