runok audit

runok audit displays recorded audit log entries. Every exec and hook evaluation is logged automatically (unless disabled), and this subcommand lets you query those entries by time range, action, or command pattern.

Usage

runok audit [options]

Flags

-c, --config <path>

See Global Flags. The audit log directory is read from the loaded config’s audit.path.

--action <allow|deny|ask>

Filter entries by the evaluation result.

--since <timespec>

Show only entries after the given time. Accepts relative durations (30m, 1h, 7d) or absolute timestamps (2026-03-01, 2026-03-01T12:00:00Z).

--until <timespec>

Show only entries before the given time. Same format as --since.

--command <pattern>

Filter entries whose command string contains the given substring.

--dir <path>

Filter entries by working directory. Only shows entries executed in the given directory or its subdirectories. The path is resolved to its canonical (absolute, symlink-resolved) form before matching.

--limit <n>

Maximum number of entries to display.

Default: 50

--json

Output entries as JSON (one object per line). Useful for piping into jq or other tools.

Examples

Show the last 50 audit log entries (default):

runok audit

Show denied commands from the last hour:

runok audit --action deny --since 1h

Show entries for git commands in JSON format:

runok audit --command git --json

Show entries from a specific date range with a custom limit:

runok audit --since 2026-03-01 --until 2026-03-07 --limit 100

Output format

In text mode (default), the output adapts to the terminal:

• TTY (interactive terminal): a column-aligned table with colored action labels. Commands are truncated to fit the terminal width. Entries are sorted oldest-first so the most recent entry appears at the bottom.

TIMESTAMP            ACTION   COMMAND
2026-03-13 19:30:00  allow    git status
2026-03-13 19:31:00  deny     rm -rf /

• Non-TTY (piped): tab-separated values without colors or truncation, suitable for further processing.

Timestamps are displayed in local time in both modes.

In JSON mode (--json), each line is a complete JSON object describing one evaluation. The full field-by-field reference — including every enum value and every “omitted when empty” condition — lives on a dedicated page: see Audit Log JSON Schema.

The most common shape worth knowing here: each entry exposes a command_evaluations array with one entry per shell command extracted from the input. Single inputs produce one entry, compound (a && b) and pipelined (a | b) inputs produce one per branch in source order, and inputs with no runnable command (comment-only, parse failure) produce an empty array. Each entry carries the rule-evaluation result (action, matched_rules) and the shell-level parse result (env, argv, redirects, pipe) side by side, so audit consumers can filter on the actual binary in one jq line:

runok audit --json | jq 'select(.command_evaluations[].argv[0] == "helmfile")'

See command_evaluations for the full per-entry field reference.

Configuration

Audit logging is configured in the global runok.yml only. Audit settings in project or local override configs are ignored. See Configuration Schema for the full reference.

~/.config/runok/runok.yml

audit:
  enabled: true
  path: ~/.local/share/runok/
  rotation:
    retention_days: 7

Log storage

Audit entries are stored as JSONL files partitioned by date (audit-YYYY-MM-DD.jsonl) in the configured directory. Files are written with append-mode and file locking, so concurrent runok invocations are safe.

Old log files are automatically removed based on rotation.retention_days.

Related

• Audit Log JSON Schema — Field-by-field reference for runok audit --json output.
• Configuration Schema — audit — Full audit config reference.
• runok exec — Commands evaluated via exec are logged.