Skip to content

Vayu CLI Reference

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

Usage

vayu-cli <COMMAND> [OPTIONS]

The command comes first. With no command at all, or only flags (vayu-cli --no-color), the usage is printed and the exit code is 1.

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.

A request body that names a file on disk (a binary body or a form-data file part) is sent only when the file lies under an allowed folder or was picked in the app (trust rule). An engine you start yourself has no grant secret, so neither the CLI nor any other caller can allow a folder or pick a file through it; allow the folder in the app's Settings once, and every engine on that workspace honours it.

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 compacted copy of the database - collections (with the paths of the spec and data files they are bound to), requests, environments, credentials and run history - written into backups/ beside it. Tabs, saved load-test values and the other state the app keeps for itself are not in it (what a backup does not hold). 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, which also counts the copy an update saves before it migrates the workspace; 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). When the desktop app fell back to another port because 9876 was held, pass the address its Dock shows (hover "Engine connected"), e.g. --daemon http://127.0.0.1:9880

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); a positive targetRps on any other mode is a 400
  • 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. The body's code tells the two apart: live_expired for a stored run whose window has passed, run_not_found for an id the engine has no row for.

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

A daemon started this way can run beside the desktop app, but only with a --data-dir of its own. Opening the app stops an engine whose /health reports the app's own data directory and leaves every other alone: a daemon on another --data-dir holds its port, and the app runs its own engine on its next port (9880-9889) instead. The app's data directory is its profile directory in a packaged build, and <repo>/engine/data in a development build, so a daemon run from engine/ with its defaults (./data) serves the same directory as the dev app, and a packaged daemon given the app's profile as --data-dir does too; the app replaces either at launch. Give a standalone daemon its own --data-dir (the engine refuses a second process on one data directory anyway).

An engine from before /health reported its data directory (#3328) is never taken over, whatever it serves, so after upgrading across that change an orphan of the old release must be quit by hand: the port-in-use error names it.

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. It also exits 1 when its database cannot be opened safely - one written by a newer Vayu, or one it cannot examine because another program holds it or the disk is full or read-only - naming the database on stderr and changing nothing (db-schema.md). 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

--data-dir is made owner-only (0700 on Linux and macOS) whatever it names, and the engine's own files under it are tightened to 0600 on every start (vayu.lock and the regular files directly in db/, db/backups/ and logs/), so give it a directory of its own rather than one that holds other things you share.

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.