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) | 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) | Cache non-zero exits the same way zero exits are cached. Off by default; transient failures shouldn't poison the cache. | |
--verify-reproducible | (flag) | 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) | 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. |