runok check

runok check evaluates a command against your runok rules and reports the decision — without actually running the command. Useful for previewing what runok would do, or for integrating with external tools like Claude Code hooks.

Usage

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

Any unrecognized flag before -- is rejected with an error to prevent typos from being silently absorbed into the command arguments.

When no command arguments are given, runok reads from stdin instead. The input format is auto-detected: JSON objects are parsed by field (tool_name for Claude Code hooks, command for generic checks), and anything else is treated as plaintext with one command per line.

Use --input-format claude-code-hook to force Claude Code hook parsing.

Flags

--input-format <format>

Input format for stdin. Currently supports claude-code-hook. When omitted, the format is auto-detected from the stdin content. Has no effect when command arguments are provided.

--output-format <format> [default: text]

Output format. Available values:

• text — Human-readable single line (e.g., deny: reason (suggestion: fix))
• json — Machine-readable JSON object with decision, reason, fix_suggestion, and sandbox fields. Fields with no value are omitted.

--verbose

Output detailed rule matching information to stderr.

Examples

Check a single command:

runok check -- git push --force
# deny: Blocked to prevent rewriting remote history (suggestion: git push)

Check with JSON output:

runok check --output-format json -- rm -rf /

{
  "decision": "deny",
  "reason": "Do not delete root",
  "fix_suggestion": "rm -rf ./build"
}

Read commands from stdin (one per line):

printf "git push\nnpm publish\n" | runok check
# allow
# deny: Publishing is not allowed

Read from stdin as JSON:

echo '{"command":"git push"}' | runok check
# allow

Force Claude Code hook format:

cat hook-input.json | runok check --input-format claude-code-hook
# allow [sandbox: default]

Exit codes

Code	Meaning
0	Evaluation completed successfully (regardless of the decision).
2	An error occurred (config error, JSON parse error, etc.).

The exit code reflects whether the check itself succeeded, not the permission decision. A deny result still returns exit code 0. Use --output-format json to programmatically inspect the decision.

When checking multiple commands (multi-line stdin), the exit code is the highest value across all evaluations.