once exec
Execute a literal action through the cache
Synopsis#
plaintext
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 |