Commands Reference

rwarden provides a unified command-line interface for path testing, configuration verification, schema export, and gateway generation.

---

1. Test URL Paths & Queries (test)

Simulate candidate path extraction, normalization, and pattern matching on an arbitrary path without starting Traefik, Caddy, or NGINX:

# Test a sensitive file path (positional or --path)rwarden test /.envrwarden test --path "/.env"# Test double URL encoding anti-evasionrwarden test "/static/%252e%252e/.env"# Test query string inspection (-q or --query)rwarden test -q "file=secret.conf" /search# Test custom HTTP methods (-X, -m, or --method)rwarden test -X POST /wp-config.php# Test custom HTTP headers (-H or --header, repeatable)rwarden test -H "X-Forwarded-Uri: /.env" /api# Test against a custom RouteWarden config file (-c or --config)rwarden test -c routewarden.json /admin/dashboard# Test client IP whitelistingrwarden test -c routewarden.json --ip "10.0.0.1" /admin# Test request body payload inspection (-b or --body)rwarden test -X POST -b "grant_type=password&user=admin" --check-body /identity/token# Pipe configuration via stdincat routewarden.json | rwarden test -c - /admin

Flags

Flag	Type	Default	Description
[path], --path	string	""	Request path to evaluate (e.g. /.env or /api/v1)
-c, --config	string	""	Path to routewarden.json (or - for stdin)
-q, --query	string	""	Query string to evaluate for path evasion payloads
-b, --body	string	""	Request body payload to evaluate for hostile content
-X, -m, --method	string	"GET"	HTTP method (e.g. GET, POST, HEAD)
-H, --header	string	""	Optional header in Key:Value format (repeatable)
--ip	string	""	Client IP address to evaluate against allowedIps
--check-query	bool	true	Enable or disable query string inspection
--check-body	bool	false	Enable or disable request body payload inspection

Example Output

🔍 Testing: GET /static/%252e%252e/.env  Candidate paths extracted (2):    - /static/%252e%252e/.env    - /.envResult: 🛑 BLOCKED (HTTP Status 403)  Reason:  block_pattern_match  Target:  /.env  Pattern: (?i)\.env

---

2. Validate Configurations (validate)

Validate a RouteWarden JSON or TCP Warden YAML configuration file before deploying:

# Validate routewarden.json directly (positional or --config)rwarden validate routewarden.jsonrwarden validate -c routewarden.json# Auto-detects routewarden.json in current directory if omittedrwarden validate# Validate tcp-warden.yaml configurationrwarden validate tcp-warden.yaml# Validate piped config via stdincat routewarden.json | rwarden validate -c -

Example Output

✔ Schema validation passed: routewarden.json is valid!  - 14 built-in block patterns active  - 5 allow rules configured  - Response mode: json (HTTP 403)  - 3 allowed IP CIDR blocks evaluated

---

3. Output JSON Schema (schema)

Output the official RouteWarden JSON Schemas directly to stdout:

# Output HTTP Gateway Schema (routewarden.json)rwarden schema > routewarden.schema.json# Output TCP Warden L4 Proxy Schema (tcp-warden.yaml)rwarden schema --tcp > tcp-warden.schema.json

---

4. Generate Gateway Configs (generate)

Compile a universal routewarden.json policy into target reverse proxy syntax:

# Traefik: dynamic YAML middleware definitionrwarden generate traefik-yaml routewarden.json > traefik-middleware.yaml# Traefik: dynamic TOML middleware definitionrwarden generate traefik-toml routewarden.json > traefik-middleware.toml# Traefik: Docker Compose labels blockrwarden generate traefik-labels routewarden.json# Caddy: Caddyfile directive blockrwarden generate caddy routewarden.json# NGINX / OpenResty: Lua init table for nginx.confrwarden generate nginx routewarden.json# TCP Warden: tcp-warden.yaml configurationrwarden generate tcp-warden routewarden.json > tcp-warden.yaml

Supported Targets

Target	Alias	Description
traefik-yaml	traefik, yaml	Traefik Dynamic File Provider YAML
traefik-toml	toml	Traefik Dynamic File Provider TOML
traefik-labels	labels, compose	Docker Compose container label syntax
caddy	caddyfile	Native Caddyfile routewarden directive block
nginx	openresty, lua	OpenResty init_by_lua_block Lua table
tcp-warden	tcp, l4	TCP Warden daemon YAML configuration

---

5. Live Gateway Sandbox (sandbox)

Spin up an ephemeral, isolated container running Traefik, Caddy, or NGINX loaded with your security policy for live testing:

# Start a Traefik sandbox on localhost:8080rwarden sandbox traefik routewarden.json# Start a Caddy sandbox with automatic test suite executionrwarden sandbox caddy routewarden.json --test# Start an NGINX sandbox in detached background moderwarden sandbox nginx routewarden.json --detach# Dry-run: view generated container command without launchingrwarden sandbox traefik routewarden.json --dry-run

Sandbox Testing Probes

When running in sandbox mode, you can execute HTTP requests against http://localhost:8080:

# Sensitive file attack (should return 403 Forbidden)curl -i http://localhost:8080/.env# Directory traversal attempt (should return 403 Forbidden)curl -i "http://localhost:8080/static/..%2f.env"# Safe RFC endpoint (should return 200 or upstream response)curl -i http://localhost:8080/robots.txt

---

6. Cleanup Sandbox Containers (cleanup)

Stop and remove all running or detached RouteWarden sandbox test containers:

rwarden cleanup

---

7. Version Information (version)

Check installed binary version:

rwarden version

---

8. Observability Stack (dashboard)

Launch and manage a turnkey cloud-native observability stack (Grafana, Grafana Loki, and Grafana Alloy) using Docker Compose to visualize real-time blocked threats, attack rates, and top offender IPs:

# Launch Grafana, Loki, and Alloy stack via Docker Compose (default: port 3000)rwarden dashboardrwarden dashboard up# Check status of running observability stack containersrwarden dashboard status# Stop and tear down the observability stackrwarden dashboard down# Export Docker Compose, Alloy, and Grafana config files to diskrwarden dashboard export ./observability

Subcommands & Flags

Subcommand / Flag	Type	Default	Description
up, start	subcommand	—	Spin up Grafana, Loki, and Alloy stack (default)
down, stop	subcommand	—	Stop and tear down running stack containers
status, ps	subcommand	—	Check container health and service URLs
export [dir]	subcommand	./observability	Export compose, Alloy, and Grafana assets to disk
--port	int	3000	Port for Grafana dashboard UI
--loki-port	int	3100	Port for Loki log engine
--dir	string	~/.routewarden/observability	Working directory storing stack files
--no-open	bool	false	Do not launch system default browser

👉 For full configuration, LogQL query cheat sheets, and custom alerts, see the Security Observability Stack Guide.