Watch Command

The watch command is Rumour's live development mode. It monitors a request file or directory for file system changes and automatically re-executes the entire workflow every time you save. Think of it as a TDD feedback loop — edit a .toml file, hit save, and Rumour instantly reports whether your request still works.

Basic Usage

rumour watch <PATH>

• <PATH> — Path to a single request file (.toml) or a directory of requests

Note: Most flags from the run command are available here too. The key difference is that watch never exits — it stays running, listening for file changes, and re-triggers a full run each time one is detected. Flags not supported in watch: --junit, --report, --record, --replay, --profile, --yes, --list-nodes, --resources.

How It Works

When you start watch, the engine does three things:

1. Runs the workflow immediately — so you get an instant baseline result, even before any files change.
2. Registers a recursive filesystem watcher — it monitors the target file, or the target directory and all of its subdirectories recursively, using the OS-native event APIs (via the notify crate).
3. Debounces change events — if you save a file multiple times in quick succession (e.g. editor auto-saves or auto-formatters saving within 500ms), Rumour coalesces them into a single re-run to avoid hammering your API.

Intelligent Event Filtering

To prevent infinite loops and unnecessary resource consumption, the watcher applies strict filtering rules on every filesystem event:

• Only Relevant Extensions: Only changes to files ending in .toml (requests/configurations), .json, or .csv (data files) will trigger a run.
• Skip Directories: Changes to directories themselves (e.g., metadata modifications or folder creation) are ignored.
• Skip Hidden Folders: Any changes inside hidden directories (such as .git/ or Rumour's internal state directory .rumour/) are automatically ignored.

Every time a relevant file in the watched path is modified, the full workflow re-runs from scratch.

Example Setup

For these examples, we use the following test workspace:

watch_example/workspace.env.toml

[variables]
base_url = "https://httpbin.org"

watch_example/requests/01_get.toml

name = "Health Check"
[request]
method = "GET"
url = "{{base_url}}/get"

watch_example/requests/02_post.toml

name = "Create Item"
[request]
method = "POST"
url = "{{base_url}}/post"

[body]
type = "json"
raw = '{"name": "test-item", "value": 42}'

Watch a Single File

rumour watch requests/01_get.toml

Output:

👁 Watching requests/01_get.toml for changes...
Running initial workflow...
  GET https://httpbin.org/get
  ✓ SUCCESS: requests/01_get.toml (1572ms)

╭──────────────────────────────────────────────────────────────────────────╮
│ RUMOUR EXECUTION REPORT                                                  │
├──────────────────────────────────────────────────────────────────────────┤
│ Total Requests:      1                                                   │
│ Successful:          1                                                   │
│ Failed:              0                                                   │
│ Skipped:             0                                                   │
│ Success Rate:        100.0%                                              │
│ Total Time:          1573ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

Actionable Recommendations:
  → Use -v -t to see detailed latency and response diagnostics.
  → Run with --json to export this report for your CI/CD pipeline.

What this output means:

• 👁 Watching requests/01_get.toml for changes... — The watcher is live and listening.
• Running initial workflow... — Rumour runs the request immediately on startup (before any changes).
• The full Execution Report is printed. This is identical to what rumour run would produce.
• The process stays alive, waiting for your next file save.

Now, when you edit and save 01_get.toml:

🔄 Change detected! Re-running workflow...
  GET https://httpbin.org/get
  ✓ SUCCESS: requests/01_get.toml (1244ms)

╭──────────────────────────────────────────────────────────────────────────╮
│ RUMOUR EXECUTION REPORT                                                  │
├──────────────────────────────────────────────────────────────────────────┤
│ Total Requests:      1                                                   │
│ Successful:          1                                                   │
│ Failed:              0                                                   │
│ Skipped:             0                                                   │
│ Success Rate:        100.0%                                              │
│ Total Time:          1257ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

What this output means:

• 🔄 Change detected! Re-running workflow... — A filesystem event was fired (file save). Rumour automatically re-ran the full workflow.
• The new report replaces the previous one in your terminal — you get a fresh, timestamped result for every save.

Press Ctrl+C to stop the watcher at any time.

Watch a Directory (Full Workflow)

rumour watch requests/

Watching a directory is the most common pattern. When any .toml file inside requests/ is modified, Rumour re-runs the entire directory as a workflow — not just the changed file. This is by design, because changing one request might affect downstream requests that depend on its extracted variables.

Output (initial run):

👁 Watching requests/ for changes...
Running initial workflow...
  GET https://httpbin.org/get
  ✓ SUCCESS: requests/01_get.toml (2008ms)
  POST https://httpbin.org/post
  ✓ SUCCESS: requests/02_post.toml (2066ms)

╭──────────────────────────────────────────────────────────────────────────╮
│ RUMOUR EXECUTION REPORT                                                  │
├──────────────────────────────────────────────────────────────────────────┤
│ Total Requests:      2                                                   │
│ Successful:          2                                                   │
│ Failed:              0                                                   │
│ Skipped:             0                                                   │
│ Success Rate:        100.0%                                              │
│ Total Time:          4074ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

Actionable Recommendations:
  → Run with --json to export this report for your CI/CD pipeline.

What this means:

• Both requests in the directory were found and executed in order.
• Total Time: 4074ms covers the full round-trip for both requests.
• The watcher is now listening on the parent directory. Any .toml save inside requests/ triggers this full 2-request workflow again.

Command Options

watch supports a subset of run flags. Flags not available in watch are marked with ✗.

Option	Short	Available	Description
--stop-on-fail	-	✓	Halt on first failure per cycle
--json	-	✓	Output results in JSON format
--verbose	v	✓	Show detailed execution summary
--trace	t	✓	Show full failure details
--heal	H	✓	Show self-healing recovery logs
--parallel	p	✓	Run requests in parallel
--hard-heal	X	✓	Reconstruct missing resources (404)
--auto-cleanup	C	✓	Delete created resources after each cycle
--quiet	q	✓	Suppress output except summary line
--download-dir	d	✓	Custom download directory
--var	V	✓	Override variables (key=value)
--header	-	✓	Add or override headers
--body	b	✓	Override request body
--extract	E	✓	Override extraction rules
--dry-run	-	✓	Don't send actual HTTP requests
--delay	-	✓	Delay between requests (ms)
--interactive	i	✓	Prompt for action on failure
--env-file	e	✓	Custom environment file
--vars	-	✓	Output variables after each cycle
--concurrency	c	✓	Max parallel requests
--step	S	✓	Step-by-step mode (with optional NODE_ID)
--junit	-	✗	Not supported in watch mode
--report	-	✗	Not supported in watch mode
--record	-	✗	Not supported in watch mode
--replay	-	✗	Not supported in watch mode
--profile	-	✗	Not supported in watch mode
--yes	y	✗	Not needed (watch auto-confirms)
--list-nodes	-	✗	Not supported in watch mode
--resources	-	✗	Not supported in watch mode

Detailed Options

Verbose Mode (-v, --verbose)

Shows the method, URL, headers, and body of each request as it fires during every cycle — identical to run -v.

rumour watch requests/ -v

Output (per cycle):

Running initial workflow...
  GET https://httpbin.org/get
  URL: https://httpbin.org/get
  ✓ SUCCESS: requests/01_get.toml (2006ms)
  POST https://httpbin.org/post
  URL: https://httpbin.org/post
  Body (json): {"name": "test-item", "value": 42}
  ✓ SUCCESS: requests/02_post.toml (2063ms)

╭──────────────────────────────────────────────────────────────────────────╮
│ RUMOUR EXECUTION REPORT                                                  │
├──────────────────────────────────────────────────────────────────────────┤
│ Total Requests:      2                                                   │
│ Successful:          2                                                   │
│ Failed:              0                                                   │
│ Skipped:             0                                                   │
│ Success Rate:        100.0%                                              │
│ Total Time:          4074ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - requests/01_get.toml  [200] [2008ms]
  - requests/02_post.toml  [200] [2066ms]

The verbose mode shows Body (json): {...} for POST requests, confirming the exact payload that was sent on each re-run.

Quiet Mode (-q, --quiet)

Suppresses all output during execution and only prints the summary line per cycle. This is the recommended mode for running watch in a background terminal while you focus on your editor — you only get notified when something changes.

rumour watch requests/ -q

Output:

👁 Watching requests/ for changes...
Running initial workflow...

No further output until a file changes. When a change is detected, just the summary line is printed — no individual request logs or report boxes.

Stop on Fail (--stop-on-fail)

Halt the workflow immediately on the first failure in each re-run cycle. Subsequent requests in that cycle are skipped. This matches the behaviour of run --stop-on-fail.

rumour watch requests/ --stop-on-fail

This is especially useful during TDD — if 01_get.toml fails, you don't want to see false results for 02_post.toml which may depend on it.

Parallel Mode (-p, --parallel)

Run all independent requests in each cycle simultaneously using Rumour's Dependency Graph engine. Useful when watching a large directory where requests are independent of each other.

rumour watch requests/ -p -c 5

The -c 5 flag caps concurrent connections at 5 per cycle.

Override Variables (-V, --var)

Pin a variable to a specific value for every re-run cycle. This is useful when you want to test against a different environment without modifying workspace.env.toml.

rumour watch requests/ -V base_url=https://staging.api.com

Every cycle will fire against staging.api.com instead of the default from your env file.

Environment File (-e, --env-file)

Use a custom environment file instead of the default workspace.env.toml. Ideal for switching between environments without editing files.

rumour watch requests/ -e staging.env.toml

Dry Run (--dry-run)

Watch for file changes and validate that all {{variables}} resolve correctly on every save — without sending any actual HTTP requests. This is useful for validating your .toml syntax and variable references during development.

rumour watch requests/ --dry-run

Every cycle will report status: 200, body: "[DRY RUN: No body sent]" for each request, confirming the graph was parsed and variables resolved successfully.

Common Use Cases

TDD API Development

The primary use case. You write a request .toml with assertions, run watch, then iterate on your API code until the watch cycle turns green.

# Terminal 1: Start the watcher
rumour watch requests/ -v

# Terminal 2: Edit your request file
# Every save in Terminal 2 triggers a full re-run in Terminal 1

CI-like Feedback During Development

Use --quiet and --stop-on-fail together for a minimal, signal-only feedback loop that mimics what your CI pipeline will do:

rumour watch requests/ -q --stop-on-fail

Multi-Environment Testing

Quickly switch between environments without touching any .toml files:

# Watch against staging
rumour watch requests/ -V base_url=https://staging.api.com

# Or use a separate env file
rumour watch requests/ -e staging.env.toml

---

Stopping the Watcher

Press Ctrl+C to terminate the watch process. The watcher exits cleanly with no cleanup required.

---

Exit Codes

Code	Meaning
0	Watcher terminated by user (Ctrl+C)
1	Failed to start — invalid path or watcher error