Pattern Syntax Overview
runok uses a pattern syntax to define which commands are allowed or denied. The basic form looks like the commands you normally type in the terminal, with additional syntax elements like wildcards (*), alternation (|), and optional groups ([]) for flexible matching.
Patterns are parsed exactly as written, with no hidden rewriting or implicit transformation. See Matching Behavior for details.
Syntax Elements
Section titled “Syntax Elements”| Syntax | Example | Description |
|---|---|---|
| Literal | git status | Exact token match |
| Wildcard | git * | Zero or more tokens |
| Glob | list-*, *.txt | * inside a literal matches zero or more characters |
| Alternation | -X|--request, main|master | Pipe-separated alternatives |
| Negation | !GET, !describe|get | Matches anything except the specified value(s) |
| Optional group | [-f], [-X POST] | Matches with or without the group |
| Flag with value | -X|--request POST | A flag-value pair matched in any order |
| Placeholder | <cmd>, <opts>, <path:...>, <var:...> | Special tokens in <...> with various behaviors (see below) |
| Backslash escape | \; | Literal match after removing the backslash |
| Quoted literal | "WIP*", 'hello' | Exact match without glob expansion |
| Multi-word alternation | "npx prettier"|prettier | Alternatives that include multi-word commands |
Placeholders
Section titled “Placeholders”Tokens wrapped in <...> are placeholders — special tokens that match dynamically rather than by exact string comparison. Each placeholder type has different matching behavior:
| Placeholder | Example | Description | Details |
|---|---|---|---|
<cmd> | sudo <cmd> | Captures the wrapped command for further rule evaluation | Command |
<opts> | env <opts> <cmd> | Absorbs zero or more flag-like tokens (starting with -) | Options |
<vars> | env <vars> <cmd> | Absorbs zero or more KEY=VALUE tokens | Variables |
<path:name> | cat <path:sensitive> | Matches against a named list of paths from definitions | Path References |
<var:name> | cmd <var:ids> | Matches against a typed variable definition (argument or command position) | Variable References |
Pattern Structure
Section titled “Pattern Structure”A pattern consists of a command name followed by argument tokens:
<command> [argument tokens...]The first token is always the command name. The remaining tokens define the argument pattern.
# Command: "git", argument tokens: ["push", "--force"]- deny: 'git push --force'
# Command: "curl", argument tokens: ["-X|--request", "POST", "*"]- allow: 'curl -X|--request POST *'Pages in This Section
Section titled “Pages in This Section”- Wildcards — Token and glob wildcards
- Alternation — Pipe-separated alternatives and negation
- Optional Groups — Tokens that may or may not be present
- Placeholders —
<cmd>,<opts>,<vars>,<path:...>placeholders - Matching Behavior — Flag inference, order-independent matching, and combined short flags