runok exec

runok exec evaluates a command against your runok rules and, if allowed, executes it — optionally within a sandbox. If the command is denied (or requires confirmation), it is not executed and exit code 3 is returned.

defaults.action: pass has no effect when runok exec is invoked directly: unlike the Claude Code hook, it has no underlying permission flow to defer to, so it falls back to the same behavior as ask (exit code 3). The one exception is the sandbox-wrapped command the Claude Code hook itself generates for a pass decision (see defaults.action) — that invocation runs under the resolved sandbox, since the hook has already deferred the permission decision to Claude Code’s own flow.

Usage

runok exec [options] -- <command> [arguments...]

The -- separator distinguishes runok flags from the command’s own flags. Any unrecognized flag before -- is rejected with an error to prevent typos from being silently absorbed into the command arguments.

A single argument after -- is interpreted as a shell command (passed to the shell). Multiple arguments are interpreted as an argv array (executed directly).

Flags

-c, --config <path>

See Global Flags.

--sandbox <preset>...

Apply a named sandbox preset from your runok configuration. Overrides any sandbox defined in the matching rule.

Repeatable. Passing --sandbox more than once merges the named presets using Strictest Wins (writable roots intersected, deny paths unioned, network access ANDed).

--verbose

Output detailed rule matching information to stderr.

Examples

Execute a command with permission checks:

runok exec -- npm test

Execute with a sandbox preset:

runok exec --sandbox strict -- npm install

Execute with multiple sandbox presets merged via Strictest Wins:

runok exec --sandbox strict --sandbox no-network -- npm install

Run a shell expression (single argument, passed to shell):

runok exec -- 'echo hello && echo world'

Exit codes

Code	Meaning
N	Command’s own exit code (on successful execution).
1	An error occurred (config error, sandbox setup failure, etc.).
3	Command was denied or requires confirmation (ask or pass).

The pass row above applies when runok exec is invoked directly. The one exception is the sandbox-wrapped command the Claude Code hook generates for a pass decision (see above) — that invocation runs under the resolved sandbox and can exit 0 instead of 3.

Related

• runok check — Evaluate commands without executing them.
• Sandbox — Configure sandbox presets.
• Denial Feedback — Configure feedback for denied commands.