What it is

rip executes the same HTTP resolution pipeline as the desktop Collection Runner and Request Chains — without a GUI. Point it at ripple.db, a team workspace folder, exported ripple-collection JSON, or import Postman, Insomnia, OpenAPI, or HAR on the fly.

Results go to stdout or a file as human text, JSON, JUnit XML, HTML, or GitHub Actions annotations.

Install & build

Install on macOS / Linux

curl -L "<release-url>/rip_<version>_<arch>" -o rip
chmod +x rip && sudo mv rip /usr/local/bin/
rip --version

GitHub release download

Native rip binaries ship on the same GitHub release as the Ripple desktop app
Use the download panel at the top of this page, or grab the asset for your OS from the release page
macOS/Linux: chmod +x rip && sudo mv rip /usr/local/bin/ — Windows: add rip.exe to your PATH

Global flags

These apply before any subcommand.

--db and --workspace are mutually exclusive for collection/env listing. Workspace mode ignores the personal DB unless you also pass --db.

Flag	Description
--db <path>	Override personal SQLite path (default: OS app-data com.ripple.app/ripple.db)
--workspace <path>	Team workspace root (file-based collections + environments)
--verbose	Resolved URLs, headers (secrets redacted), script logs, pass/fail timing
--verbose-response	Print response body on failed requests (truncated to 2000 chars)
--quiet	Suppress non-essential success messages

Command reference

rip [GLOBAL FLAGS] <command>

Commands:
  run          Run collections, chains, or imported files
  newman       Newman-compatible Postman collection runner
  request      Send individual requests
  collections  List, export, import, validate collections
  env          List and show environments
  spec         OpenAPI validate and lint
  workspace    Workspace info (requires --workspace)
  mock         Mock server control (headless)
  config       Configuration helpers
  help         Print help

rip config path — print resolved ripple.db and workspace paths

rip run collection & chain

run collection executes all HTTP requests in sort_order with optional iterations, data files, filters, and assertions. run chain runs saved multi-step chains with JSON-path extractions.

Collection run

rip run collection ./collections/smoke.json \
  --env ./environments/staging.json \
  --reporter junit \
  --output results.xml \
  --bail

rip --workspace ~/team-workspace run collection payments-api \
  --environment default \
  --env-var token=$TOKEN \
  --reporter github

Collection target resolution

Path to .json file → load as ripple-collection
With --workspace → collection slug or name in workspace
Otherwise → collection name or numeric id in ripple.db

Filtering

--folder Auth — requests whose name or folder starts with Auth
-i / --folder-id <uuid> — Postman folder UUID (nested folders included)
--request health — request name substring (case-insensitive)

Chains

rip run chain "My API" "Login flow" --environment Staging --bail
Loaded from chains array in exported JSON or settings.chains_{collectionId} in ripple.db

Import & run

rip run postman / postman-v3

Postman v2 JSON or v3 directory (collection.yaml + *.request.yaml)
Nested folders → request names like Auth/Login
Imports variables, methods, URLs, headers, bodies, basic auth types
Postman event scripts preserved and run via Boa pm.* sandbox

rip run har

HAR 1.x capture — each log.entries[] request becomes a run step
Entries without a request object are skipped

rip run insomnia

Insomnia v4 export (_type: export, resources array)
Imports name, method, URL, headers, raw body

rip run openapi

OpenAPI 3 JSON or YAML — one smoke request per path + method
URL template: {{baseUrl}}<path> from first servers[].url
Default assertion: status 200 on each request

rip request

rip request raw POST https://api.example.com/items \
  --header "Content-Type: application/json" \
  --body '{"name":"widget"}' \
  --timeout 60

rip request send

Send one saved request from ripple.db by name or numeric id
--collection-id <id> required for named/id lookup
rip request send 42 --collection-id 3

rip request raw

Ad-hoc METHOD + URL without a saved collection
--header "Name: value" (repeatable), --body, --body-file
--timeout (default 30s), --proxy, --insecure to disable TLS verify

Collections, env & workspace

rip collections

list — id or slug + name
export <name> -o <file.json> — ripple-collection JSON
import <file.json> — parse and validate
validate <file.json> — format only; exit 0 on success

rip env

list — named environments from DB, workspace, or --env file
show <name> — key=value lines

rip workspace (requires --workspace)

info — display name and root path
collections-list — slug<TAB>name

Mock server & OpenAPI spec

rip mock

Headless mock server for CI — definitions at {ripple data}/mocks/{name}.json
list, status, start <name> (default port 4010), stop <name>
Route JSON matches desktop Mock Servers format; only one server at a time

rip spec

validate <file> — syntax + required fields; exit 0 on success
lint <file> --mode standard|extended --fail-on-warning
Supports JSON and YAML — same parser as rip run openapi

Newman compatibility

rip newman run <collection> accepts Newman-style flags and maps them internally. v2 JSON and v3 directories both work as the collection argument.

Newman flag	rip newman run	Status
newman run <file>	rip newman run <file>	✓
-e, --environment	-e / --environment	✓
-g, --globals	-g / --globals	✓
-d, --iteration-data	-d / --iteration-data	✓
-n, --iteration-count	-n / --iteration-count	✓
--folder	--folder (prefix filter)	✓
-i, --folder-id	-i (Postman folder UUID)	✓
--env-var / --global-var	same	✓
--bail	--bail	✓
-r cli,junit + exports	-r + --reporter-junit-export	✓
--timeout-request (ms)	--timeout-request	✓
--delay-request (ms)	--delay-request	✓
--insecure	--insecure	✓
--ignore-redirects	—	✗

Newman → rip

# Newman
newman run collection.json -e staging.json -r junit \
  --reporter-junit-export results.xml --bail

# rip (equivalent)
rip newman run collection.json -e staging.json \
  --reporter-junit-export results.xml --bail

Shared run flags

Used by run collection, run postman, run postman-v3, run har, run insomnia, and run openapi.

Variable precedence: globals → environment → collection → data row → --global-var / --env-var overrides (overrides win).

Flag	Default	Description
--env <path>	—	Postman-style or Ripple environment JSON file
--environment <name>	—	Named environment from DB or workspace
--globals <path>	—	Globals JSON file
--data <path>	—	CSV or JSON data file for parameterized iterations
--iterations <N>	1	Repeat full collection N times
--reporter <kinds>	human	Comma-separated: human, json, junit, html, github
--output <path>	stdout	Write report to file
--parallel <N>	1	Run up to N requests concurrently (no scripts)
--bail	off	Stop on first failed request or assertion
--insecure	off	Disable TLS certificate verification
--timeout <secs>	30	Per-request timeout
--delay <ms>	0	Delay between requests
--proxy <url>	—	HTTP proxy URL
--folder <prefix>	—	Filter by folder/name prefix
--request <needle>	—	Filter by request name substring
--env-var KEY=VALUE	—	Override environment variable (repeatable)
--global-var KEY=VALUE	—	Override global variable (repeatable)
--fail-on-error	on	Exit 1 on HTTP ≥ 400 or transport error
--fail-on-assertion	on	Exit 1 on declarative assertion failure

Reporters

--reporter value	Aliases	Output
human	console, text	Pass/fail lines with status codes and assertion messages
json	—	Full RunSummary JSON (results, counts, assertion failures)
junit	junit-xml	CI-friendly testsuite XML
html	—	Standalone HTML report
github	github-actions	::group::, ::error::, ::notice:: workflow commands

Declarative assertions

JSON assertions on each request via the tests field — no JavaScript required. Store as a JSON array on the request in ripple-collection exports or StoredRequest.tests in the DB.

HTTP status < 400 and all assertions pass → pass. Use --fail-on-assertion false to treat assertion failures as warnings without failing CI.

Field	Type	Description
status	number	Expected HTTP status code
jsonPath	string	JSON path ($.field, $..nested)
equals	any JSON	Value at jsonPath must equal this
exists	boolean	true = path must exist; false = must not exist
contains	string	Body or jsonPath value must contain substring
header	string	Header name (case-insensitive)
headerContains	string	Header value must contain substring (requires header)
timeMsLt	number	Response time must be less than N milliseconds

Example tests array

"tests": "[{\"status\":200},{\"jsonPath\":\"$.id\",\"equals\":42},{\"header\":\"Content-Type\",\"headerContains\":\"json\"},{\"timeMsLt\":3000}]"

Postman scripts (pm.*)

Postman pre-request and test scripts run in a Boa JavaScript sandbox embedded in the binary. Scripts import from Postman event blocks on v2 JSON, or from v3 .resources/scripts/ when present.

API	Support	Notes
pm.environment / pm.globals / pm.collectionVariables	✓	get/set/has/unset
pm.request (url, method, body, headers)	✓	Pre-request overrides
pm.test / pm.expect	✓	Common assertion chains
pm.response.to.have.status / .header / .body	✓	Test scripts
pm.sendRequest	✓	Sync/blocking HTTP via native bridge
pm.cookies.get/set/clear	✓	In-memory jar; SQLite when collection has DB id
pm.utils (base64, uuid)	✓
console.log	✓	Shown with --verbose

No async callback-style pm.sendRequest — synchronous only
No full Chai parity — common patterns work; exotic matchers may not
No Nunjucks {% %} — desktop-only
Import-time conversion: common Postman test patterns auto-convert to declarative tests JSON

Postman migration

Postman feature	rip	How
Collection JSON export (v2.x)	✓	rip run postman or rip newman run
Postman v3 directory	✓	rip run postman-v3 <dir>
Pre-request & test scripts	✓	Boa pm.* sandbox
OpenAPI YAML smoke	✓	rip run openapi spec.yaml
HAR replay	✓	rip run har capture.har
Nunjucks {% %} templates	✗	Desktop-only

Exit codes

Code	Meaning
0	Success — no failures per --fail-on-error / --fail-on-assertion
1	One or more failures, or --bail stopped early
2	Usage / configuration error

rip run collection ./ci/smoke.json \
  --reporter junit --output test-results.xml --bail
echo $?  # 0 = pass, 1 = fail

Feature matrix

Execution & runners

Collection runner, folder/request filters, Postman scripts, iterations, CSV/JSON data files
Request chains, --bail, --delay, single saved request, ad-hoc raw requests
Declarative assertions, Newman-compatible runner, OpenAPI spec lint
Postman v2/v3, HAR, Insomnia, OpenAPI smoke import + run
Headless mock server, --parallel N, multi-reporter runs, GitHub Action composite

HTTP & auth (via ripple-core)

All standard HTTP methods, query params, headers, body types including multipart
{{variable}} interpolation and dynamic {{$uuid}} generators
Cookie jar inject + capture, SSL verify, timeout, proxy, follow redirects
Basic, Bearer, API Key, OAuth 2.0/OIDC, AWS SigV4, Digest, Hawk, NTLM, mutual TLS

Explicitly not in CLI

WebSocket, SSE, gRPC, Socket.IO — skipped in runner (same as desktop)
Nunjucks {% %} templates, GUI response viewer, Load Test Lab, SQL, Design Studio
OAuth browser authorization UI — use desktop or pre-provision tokens

Example workflows

GitHub Actions workflow

- name: Run API smoke tests
  run: |
    rip run collection ./ci/smoke.json \
      --env ./ci/staging.json \
      --reporter github \
      --bail

Postman in CI (no export step)

rip run postman ./postman/My-API.json \
  --env ./postman/staging.environment.json \
  --reporter html --output report.html --timeout 60

CI smoke test (JUnit)

rip run collection ./ci/smoke.json --env ./ci/staging.env.json --reporter junit --output test-results.xml --bail

GitHub Actions

Use composite action .github/actions/rip-cli or inline rip run collection with --reporter github

Mock server in CI

rip mock start my-api → rip run collection ./ci/smoke.json → rip mock stop my-api

Workspace + named environment

rip --workspace ~/acme-api run collection billing --environment production

Docker & npm

docker run --rm -v "$PWD:/work" -w /work rip-cli \
  run collection ./ci/smoke.json --reporter junit --output /work/results.xml

Docker

docker build -f docker/Dockerfile -t rip-cli .
Mount project dir: docker run --rm -v "$PWD:/work" -w /work rip-cli run collection ./smoke.json
ripple.db is not in the image — mount it or use collection JSON + --env files

npm wrapper

Package @postboy/rip-cli — Node launcher only; native binary shipped separately
rip.js resolves RIP_BIN, target/release/rip, target/debug/rip, or PATH
For npx rip just works, a postinstall binary download step is planned