For AI agents: this page as Markdown · llms.txt · JSON Schema

#Writing command-line rules

Structural tool-call rules catch commands an agent should never run: git push --force, rm -rf, --no-verify. Every example ran through the engine. FLAG: the rule fired. PASS: it stayed quiet.

Internal testing: Rerail's latest release ships code rules only, not tool-call rules. See Internal testing.

#Why a regex and not similarity

A structural rule states the exact command; a similarity threshold cannot.

#Anatomy of a rule

A rule pairs a match condition with the tool calls it reads and what to tell the agent.

{
  "id": "oss:no-force-push",
  "mode": "steer",
  "match": { "field": "input.command", "regex": "\\bgit\\s+push\\b[^\\n]*\\s--force(?:\\s|=|$)" },
  "sample": { "source": "tool:Bash", "boundary": "tool-call" },
  "action": { "content": "Do not force-push: it rewrites published history. Ask the user first." },
  "repeat": { "mode": "always" }
}

• match: the test, and the field it reads.
• sample: which tool calls the rule reads.
• mode, action, repeat: what happens, and how often, when it fires.

#Fields

Command rules usually read input.command, one string argument. A missing or non-string argument never matches.

#The regex dialect

Patterns use the Rust regex crate, which runs in linear time: no command can make a rule hang.

• Unanchored. git push matches anywhere in the argument. Add ^ / $ deliberately.
• . stops at a newline. Without (?s), .* and [^\n]* behave the same.
• No look-around or backreferences. Use a not condition instead (step 6).

In JSON, double every backslash: the regex \bgit\s+push\b is written "\\bgit\\s+push\\b".

#Seven steps to a good command regex

Build the force-push rule from a naive first attempt, fixing one failure at a time.

#1. Start from the naive literal, and watch it fail

The literal misses extra spaces, later flags and -f, and fires on legit.

{ "field": "input.command", "regex": "git push --force" }

#2. Bound the words and allow anything in between

\b stops legit matching git. \s+ absorbs any run of spaces. [^\n]* lets arguments sit between subcommand and flag, on the same line only.

{ "field": "input.command", "regex": "\\bgit\\s+push\\b[^\\n]*--force\\b" }

#3. End a flag with a delimiter, not \b

--force\b also matches --force-with-lease. End a flag with whitespace, = or end of command, and require whitespace before it.

{ "field": "input.command", "regex": "\\bgit\\s+push\\b[^\\n]*\\s--force(?:\\s|=|$)" }

#4. Cover short and bundled flags

Match any single-dash cluster containing the letter, so -f, -uf and -fu all count.

{ "field": "input.command", "regex": "\\bgit\\s+push\\b[^\\n]*\\s-[A-Za-z]*f[A-Za-z]*\\b" }

Flags are case-sensitive: leave (?i) off unless the tool ignores case.

#5. Think about chained and multi-line commands

Agents chain commands with &&, ; and |. ^ anchors to the start of the whole argument, so anchor on a separator instead:

{ "field": "input.command", "regex": "(?:^|[;&|]\\s*)rm\\s+-[A-Za-z]*r" }

#6. Use not where you would reach for look-around

There is no (?!…). Write the exception as a second, not condition.

{
  "all": [
    { "field": "input.command", "regex": "\\brm\\s+-[A-Za-z]*r[A-Za-z]*f|\\brm\\s+-[A-Za-z]*f[A-Za-z]*r" },
    { "not": { "field": "input.command", "regex": "\\brm\\s+-\\w+\\s+(?:\\./)?(?:tmp|build|dist|node_modules)(?:/|\\s|$)" } }
  ]
}

#7. Know the limit: a regex does not parse shell

A regex sees characters, not shell syntax, so it cannot tell a flag from the same text in a quoted string:

This is rare and costs one unneeded steer. If it recurs, tighten the prefix (step 5); don't model quoting.

#When not to use a regex

Use the simplest test that states the rule; often that is contains or eq.

• contains: one literal is the whole signal, such as --no-verify.
• eq: exactly one full command is forbidden. It compares byte for byte, so prefer it for tool names and paths.

#Beyond the command line

Match shells across hosts, paths under any argument name, and secrets in any argument.

Every host names its shell differently. Bind the rule to tool:* and name the shells:

{
  "match": { "all": [
    { "field": "tool.name", "regex": "^(?:Bash|bash|shell|run_terminal_cmd)$" },
    { "field": "input.command", "regex": "\\bgit\\s+push\\b[^\\n]*--force\\b" }
  ] },
  "sample": { "source": "tool:*", "boundary": "tool-call" }
}

Paths, whatever the argument is called. Write tools use file_path or path; cover both with any:

{ "any": [
  { "field": "input.file_path", "regex": "(?:^|/)\\.git/" },
  { "field": "input.path", "regex": "(?:^|/)\\.git/" }
] }

Secrets in any argument. input is all arguments as one JSON string, so one rule covers commands, file contents, and URLs:

{ "field": "input", "regex": "ghp_[A-Za-z0-9]{36}" }

#Test it, then install it

Test each rule against real cases, measure its noise, then install it.

1. Write the cases first. For each rule, list at least:

• one command it must flag;
• one near-miss it must pass;
• if it reads the command line, a tool result that echoes the command and must pass.

2. Run them through the engine. Put the rule and its cases in one conversation draft file, then test it:

{
  "kind": "conversation",
  "rule": {
    "id": "oss:no-force-push",
    "mode": "steer",
    "match": { "field": "input.command", "regex": "\\bgit\\s+push\\b[^\\n]*\\s--force(?:\\s|=|$)" },
    "sample": { "source": "tool:Bash", "boundary": "tool-call" },
    "action": { "content": "Do not force-push: it rewrites published history. Ask the user first." },
    "repeat": { "mode": "always" }
  },
  "cases": {
    "caught": [
      { "source": "tool:Bash", "boundary": "tool-call", "text": "{\"command\":\"git push --force origin main\"}", "input": "{\"command\":\"git push --force origin main\"}" }
    ],
    "passed": [
      { "source": "tool:Bash", "boundary": "tool-call", "text": "{\"command\":\"git push --force-with-lease origin main\"}", "input": "{\"command\":\"git push --force-with-lease origin main\"}" },
      { "source": "tool:Bash", "boundary": "tool-call", "text": "hint: use 'git push --force' to overwrite" }
    ]
  }
}

rerail rules test no-force-push.draft.json

It exits non-zero when a case fails.

3. Measure noise before blocking. Search your sanctioned commands (scripts, CI, docs) with the same pattern. rg uses the same Rust dialect, with single backslashes:

rg '\bgit\s+push\b[^\n]*\s--force(?:\s|=|$)' scripts .github docs

Keep mode: "steer", not "block", while it still matches sanctioned commands, such as rm -rf in a cleanup script.

4. Install it. rerail rules add stores the rule in your library and adds it to the current checkout's repository:

rerail rules add no-force-push.draft.json

It runs in Log until a person approves it: rerail rules approve oss:no-force-push or the dashboard (approval).

#Errors you will meet

Each validation error names the part of the rule at fault; the table gives the fix.

#Checklist

Check every rule against this list before installing it.

• The field is as narrow as possible: input.command, not input.
• Commands and subcommands are wrapped in \b…\b; separators are \s+, not a single space.
• Flags end in (?:\s|=|$), not \b — unless you mean to catch longer flags too.
• Short flags cover bundles: -[A-Za-z]*f[A-Za-z]*.
• [^\n]* between parts, so the match stays on one line.
• Anchored with (?:^|[;&|]\s*) if position matters — never a bare ^ on a command.
• Exceptions are a not condition, not look-around.
• (?i) only where the tool ignores case (SQL, not git flags).
• Shells from every host named in tool.name, or the rule bound to the one tool it targets.
• At least one FLAG case, one near-miss PASS case, and one tool-result PASS case, run through the engine.
• Noise checked against the repository's own sanctioned commands before mode is set to block.
• repeat set to always, and an action.content that says what to do instead.