Vayu CLI Reference¶

The vayu-cli tool executes HTTP requests and load tests via the Vayu Engine daemon.

Usage¶

vayu-cli <COMMAND> [OPTIONS]

Commands¶

run¶

Execute a request or load test from a JSON file.

vayu-cli run <file.json>

The CLI automatically detects whether the JSON file contains a single request or a load test configuration based on the presence of mode, duration, or iterations fields.

Examples:

# Execute a single request
vayu-cli run request.json

# Execute a load test
vayu-cli run load-test.json

# Use custom daemon URL
vayu-cli run request.json --daemon http://localhost:9999

backup¶

Take one snapshot of the workspace database and print where it was written.

vayu-cli backup

The snapshot is a complete, compacted copy of everything the engine stores - collections, environments, credentials and run history - written into backups/ beside the database. It is taken through the running daemon on purpose: the engine holds the database open, and copying that file by hand is not safe under WAL, because the -wal beside it holds committed transactions the main file does not.

The path is the only thing printed on stdout, so a script can capture it:

SNAPSHOT=$(vayu-cli backup)

Exit code 1 with the engine's message on stderr if the daemon is unreachable or refuses - including while another backup is still running, which answers 409. How many snapshots are kept is the maxBackupsRetained setting; restoring one is a manual copy with the engine stopped, described in Architecture.

Options¶

Option	Description
`-h, --help`	Show help message
`-v, --verbose [LEVEL]`	Enable verbose output. LEVEL is 0 (warn/error), 1 (info) or 2 (debug); `-v`/`--verbose` on its own means 1. A level outside 0-2, or one that is not a whole number, is refused with exit code 1. `vayu-cli` reads `-v` the same way `vayu-engine` has always read it; `-v` used to mean `--version` here and no longer does.
`--version`	Show version information (long form only - `-v` is `--verbose`)
(anything else)	Refused, naming the argument, with exit code 1
`--no-color`	Disable colored output
`--daemon <url>`	Vayu Engine URL (default: http://127.0.0.1:9876)

Request File Format¶

Single Request¶

{
  "method": "GET",
  "url": "https://api.example.com/users",
  "headers": {
    "Authorization": "Bearer {{token}}"
  },
  "body": {
    "type": "json",
    "content": "{\"name\":\"John\"}"
  },
  "environmentId": "env_1234567890",
  "elements": [
    { "kind": "script.post", "config": { "script":
      "pm.test('Status is 200', () => pm.expect(pm.response.code).to.equal(200));" } }
  ]
}

Load Test¶

{
  "request": {
    "method": "GET",
    "url": "https://api.example.com/users",
    "headers": {},
    "body": {
      "type": "none",
      "content": ""
    }
  },
  "mode": "constant_rps",
  "targetRps": 1000,
  "duration": "60s",
  "environmentId": "env_1234567890",
  "testScript": ""
}

Load Test Modes:

constant_rps: Open-loop - dispatch at targetRps for duration (use maxInFlight to cap outstanding requests)
constant_concurrency: Closed-loop - hold concurrency in-flight requests for duration
ramp_up: Closed-loop - ramp concurrency startConcurrency → concurrency over rampUpDuration, then hold to duration (total)
iterations: Closed-loop, bounded - issue iterations total requests at concurrency

Output¶

Single Request¶

The CLI prints: - HTTP status code and status text - Response time - Response size - Headers - Body (formatted JSON if applicable) - Test results (if test script provided)

Example output:

200 OK
Time: 245.5 ms
Size: 1024 bytes

Headers:
  content-type: application/json
  content-length: 1024

Body:
{
  "id": 1,
  "name": "John"
}

Load Test¶

The CLI prints: - Run ID - Link to the live metrics stream

Example output:

Run ID: run_1234567890
Monitor status at: http://127.0.0.1:9876/runs/run_1234567890/live

Use that URL to stream real-time metrics via Server-Sent Events (SSE). It serves from the engine's in-memory collector, and a finished run stays readable for the liveRetentionMs window (default 60s, GET /config) - a reader attaching late still gets the run's ticks replayed from the start. Once that window expires, or for a run id the engine has never seen, it returns 404 with a hint pointing at GET /runs/:runId/report for the stored report.

Prerequisites¶

The Vayu Engine daemon must be running before using the CLI:

# Start daemon (in another terminal)
./engine/build/vayu-engine

# Then use CLI
vayu-cli run request.json

The daemon exits 1 if it cannot take its port, naming the address on stderr - another process is listening there. Use --port to pick a different one, and --daemon to point the CLI at it. An ordinary shutdown exits 0.

Its arguments are checked before anything starts, and one that cannot be acted on is refused on stderr with exit code 1 rather than dropped:

Daemon flag	Accepts
`-p, --port <PORT>`	A whole number from 1 to 65535
`-d, --data-dir <DIR>`	A directory path
`-v, --verbose [LEVEL]`	0 (warn/error), 1 (info) or 2 (debug); `-v` on its own means 1

At -v 2, every route on the management server and every capture on a webhook inbox writes one request line - method, path, status, duration and response bytes, never the query string, headers or body (issue #1510). -v 1 shows only the non-2xx ones; -v 0 still shows a 5xx, because an engine failure is not something a quiet run should hide:

$ vayu-engine --verbose 2
...
13:57:19.123 DEBUG http     GET /health 200 0.4ms 61B
13:57:20.456 DEBUG http     GET /inbox 200 1.3ms 412B
13:57:21.789 INFO  http     GET /collections/missing 404 0.6ms 42B

See Logging for the record behind that rendering, its fields, and why a 2xx line is debug while a 3xx/4xx/5xx line is info/warn.

$ vayu-engine --port notanumber
vayu-engine: --port expects a number between 1 and 65535, got "notanumber"

$ vayu-engine --port
vayu-engine: --port expects a port number, and nothing follows it

$ vayu-engine --data-dir --port 9999
vayu-engine: --data-dir expects a directory, got "--port" - a value starting with "-" reads as another flag

$ vayu-engine --prot 9999
vayu-engine: unknown argument "--prot" - run vayu-engine --help for the arguments it takes

Three rules behind those, and both binaries follow them:

A flag that takes a value is refused when nothing follows it. It never falls back to the default silently, which is how a flag that was typed used to have no effect and leave no trace.
A value beginning with - is refused, because it is far more often the next flag than a value. vayu-engine --data-dir --port 9999 used to create a data directory literally named --port, database and lock file inside, and then listen on the default port. A path that genuinely starts with - is reachable as ./-name.
An argument matching no flag is refused, naming it and pointing at --help. A mistyped flag used to be indistinguishable from passing none.

--verbose is exempt from the first rule alone: its level is optional, so -v with nothing after it is verbosity 1, as it has always been.

Error Handling¶

The CLI returns non-zero exit codes on errors:

1: Command error (invalid file, connection failed, etc.)
0: Success

Error messages are printed to stderr with details about what went wrong.

Examples¶

Basic Request¶

# Create request.json
cat > request.json << EOF
{
  "method": "GET",
  "url": "https://httpbin.org/get",
  "headers": {},
  "body": {"type": "none", "content": ""}
}
EOF

# Execute
vayu-cli run request.json

Load Test with Verbose Output¶

vayu-cli run load-test.json --verbose 2

Custom Daemon Port¶

vayu-cli run request.json --daemon http://localhost:9999

Disable Colors (for scripts)¶

vayu-cli run request.json --no-color > output.txt

Integration¶

The CLI is designed for: - CI/CD pipelines - Automated testing - Scripting and automation - Command-line workflows

For interactive use, prefer the Electron UI which provides a richer experience.