| title | Pattern Syntax Overview | ||
|---|---|---|---|
| description | Learn the pattern syntax for matching commands in runok. | ||
| sidebar |
|
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 | 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:...> |
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 |
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 |
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 *'- 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
:::note
Pattern syntax and when expressions work on string tokens. If you need to parse structured arguments (e.g., GraphQL queries, URLs), see Extensions.
:::