Rules

Manage HTTPeep traffic manipulation rules from the command line: list, validate, test, upsert, delete, import, export, and reset rulesets.

The rules subcommand gives you full command-line control over HTTPeep's traffic routing rules. You can list active rules, add new forwarding rules, test whether a URL matches any rule, export your ruleset for version control, import rules on a new machine, and reset everything to a clean state.

rules list

List all currently configured rules.

httpeep-cli rules list
httpeep-cli --format json rules list

rules export

Export all rules to JSON. Use this to back up your ruleset or commit it to version control.

# Export to stdout
httpeep-cli rules export

# Export to a file
httpeep-cli rules export --output rules-backup.json

rules import

Import rules from a JSON or YAML file.

# Replace all non-builtin rules (default)
httpeep-cli rules import ./rules.yaml

# Merge with existing rules
httpeep-cli rules import ./rules.yaml --mode merge

Flag	Description	Default
`--mode <mode>`	Import mode: `replace` or `merge`	`replace`

rules validate

Validate a rule payload against the current store state before applying it.

# Upsert semantic validation
httpeep-cli rules validate --rule-file ./rule.yaml

# Replace semantic validation
httpeep-cli rules validate --replace --rule-file ./rules-full.json

rules test

Test whether a given URL and method match any active rule, and see which rule would apply.

httpeep-cli rules test \
  --url "https://api.example.com/v1/users" \
  --method GET \
  -H "X-Debug: 1"

rules upsert

Create or update a rule with merge (upsert) semantics. If a rule with the same ID exists, it is updated; otherwise a new rule is created.

httpeep-cli rules upsert --map-remote "api.example.com=http://127.0.0.1:3000"

You can also provide full rule JSON or a rule file:

httpeep-cli rules upsert --rule '{"id":"tmp-rule","description":"demo","enabled":true,"match":{}}'
httpeep-cli rules upsert --rule-file ./rule.yaml

rules delete

Delete a rule by its ID.

httpeep-cli rules delete --id my-rule-id

rules replace

Replace all non-builtin rules with the provided payload. This is a destructive operation — make sure to export your current rules first.

httpeep-cli rules replace --rule-file ./rules-full.json

rules replace removes all non-builtin rules before importing the new set. Export your rules with rules export first if you may need them later.

rules reset

Reset all rules to the builtin-only defaults. This removes every custom rule.

httpeep-cli rules reset

rules reset permanently deletes all custom rules. Export your rules first with rules export if you may need them later.

rules run

Run an arbitrary command with temporary rules applied. The rules are automatically rolled back when the command exits, so they never pollute the global ruleset.

httpeep-cli rules run \
  --map-remote "api.example.com=http://127.0.0.1:3000" \
  -- httpeep-cli request --method GET --url "https://api.example.com/users"

Agent-friendly JSON output:

httpeep-cli rules run \
  --json \
  --reject "api.example.com/orders=503" \
  -- httpeep-cli replay --id s1

Exit code convention:

If rule parsing or validation fails, rules run exits non-zero.
If the executed command fails, rules run exits with the command's exit code.
With --json, the output includes exit_code and success fields.

Shortcut rule parameters

Several commands (rules upsert, rules replace, rules validate, rules run, request, replay) accept shortcut parameters for common rule patterns without writing full JSON.

Flag	Format	Description
`--rule`	Inline JSON string	Full rule JSON (repeatable)
`--rule-file`	File path	Rule file path, JSON or YAML (repeatable)
`--map-remote`	`<match>=<target>`	Redirect matching requests to another host
`--map-local-file`	`<match>=<file_path>`	Serve a local file for matching requests
`--inline-response`	`<match>=<status>:<mime>:<content>`	Return an inline response
`--reject`	`<match>=<status>`	Reject matching requests with a status code
`--delay`	`<match>=<ms>`	Add a delay in milliseconds
`--throttle`	`<match>=<spec>`	Throttle bandwidth (e.g. `100`, `req=100,res=200`)

<match> supports:

host — e.g. api.example.com
host/path — e.g. api.example.com/users
/path — e.g. /api/health
Full URL — e.g. https://api.example.com/v1/users
Wildcards — e.g. *.example.com

Examples

Map remote:

httpeep-cli rules upsert --map-remote "api.example.com=http://127.0.0.1:3000"

Map local file:

httpeep-cli request --method GET --url "https://example.com/banner" \
  --map-local-file "example.com/banner=./fixtures/banner.json"

Inline response:

httpeep-cli request --method GET --url "https://api.example.com/health" \
  --inline-response "/health=503:text/plain:maintenance"

The content part supports @file to read from a file. If you need a literal @ at the start, write @@....

Reject:

httpeep-cli request --method GET --url "https://api.example.com/orders" \
  --reject "api.example.com/orders=503"

Delay:

httpeep-cli request --method GET --url "https://api.example.com/feed" \
  --delay "api.example.com/feed=300"

Throttle:

httpeep-cli request --method GET --url "https://api.example.com/feed" \
  --throttle "api.example.com/feed=req=100/200,res=150"

--throttle supports the shorthand 100 which means the same speed for both request and response.

On this page