// command line

Command Line & CI

The resonance command runs the requests, folders and saved runners of a collection without the desktop app. It is a single static binary built on the same execution engine as the app, so scripts, variables, authentication, cookies, proxies and certificates behave exactly as they do in the editor — in a pipeline, a container, or on a server.

What It Is For

  • Run the smoke tests you built in the Collection Runner on every push or merge request
  • Run a single request, a folder, or a whole collection from a git checkout, in the order shown in the sidebar
  • Produce JUnit XML that GitHub, GitLab, Jenkins or Azure Pipelines render as test results
  • Fail the pipeline through the exit code when a request or a test fails

Collections saved by Resonance 3 are plain YAML directories, and runner definitions live inside them as runners/<name>.yaml, so everything the command needs is committed next to your code. Secrets are never in those files; they are injected at run time (see Variables and secrets).

Installing

Linux and macOS

One line downloads the archive for your platform, verifies it against the release’s SHA256SUMS, and installs the binary into /usr/local/bin when that is writable, otherwise into ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/db-mobile/resonance/main/install.sh | sh

Pin a version or choose the directory:

curl -fsSL https://raw.githubusercontent.com/db-mobile/resonance/main/install.sh | sh -s -- --version 3.5.0 --dir ~/.local/bin
  • The script also reads RESONANCE_VERSION, RESONANCE_INSTALL_DIR and RESONANCE_TARGET (to override platform detection, e.g. aarch64-unknown-linux-musl)
  • It never calls sudo; prefix the sh with sudo yourself for a system directory you cannot write to
  • Prefer a manual install? Every release carries resonance-cli_<version>_<target>.tar.gz archives for Linux x86_64 and arm64 (static, no system libraries needed) and macOS (universal), plus SHA256SUMS. Unpack and put resonance on your PATH

Windows

Download resonance-cli_<version>_x86_64-pc-windows-msvc.zip from the release, check it against SHA256SUMS, and put resonance.exe on your PATH. On GitHub Actions the setup action below does this for you.

GitHub Actions

The repository doubles as a setup action for Linux, macOS and Windows runners. Referencing it at a release tag installs that version:

- uses: db-mobile/resonance@v3.5.1
  # with:
  #   version: 3.5.1        # pick another release explicitly
- run: resonance --version

The action exposes version and path outputs. uses: db-mobile/resonance@main installs the latest release.

Running Requests

resonance run collections/petstore                      # every request, in sidebar order
resonance run collections/petstore pets                 # one folder, recursively
resonance run collections/petstore pets/create-pet      # one request by file path
resonance run collections/petstore "Create pet"         # one request by name
resonance list collections/petstore                     # what the collection offers

The first argument is the collection directory, the one holding collection.yaml. Each further argument selects what to run, in the order given:

  • A request file path relative to the collection, with or without .yaml — stable under git and what resonance list prints
  • A folder path — runs every request below it, in the order shown in the app
  • A request id or its display name (exact match first, then case-insensitive). A name shared by several requests is an error that lists the candidates; use the file path instead

No selector runs the whole collection. The base URL, default headers, inherited authentication, variables and scripts come from the collection files exactly as in the app.

Running a Saved Runner

resonance run collections/petstore --runner smoke

--runner takes the file stem of runners/<stem>.yaml, the runner’s name or its id, and runs its queue with the overrides, iteration count, delay, stop-on-error setting and data file saved in the app. It cannot be combined with request selectors. Flags override the saved values:

  • -n, --iterations N — run the queue N times (1–1000)
  • -d, --data FILE — a CSV or JSON data file, one iteration per row; replaces the runner’s data file
  • --delay MS — pause between requests
  • --bail / --no-bail — stop at the first failed request or keep going. Plain runs default to --no-bail so CI sees every failure; a runner uses the Stop on error setting from its file

The same flags work without --runner, so resonance run collections/petstore users -n 3 --data rows.csv is a data-driven run of one folder.

Variables and Secrets

Values are layered, later layers winning:

  1. The collection’s own variables (variables.yaml, committed)
  2. --env-file FILE — an environment exported from the app (Export or Export All in the environment manager). Add --env NAME when the file holds several environments
  3. RESONANCE_VAR_<KEY> environment variables — the key keeps its case, so RESONANCE_VAR_apiToken sets {{apiToken}}
  4. --var KEY=VALUE, repeatable

Secrets are never written to collection files or environment exports; they come from your CI secret store at run time, for example RESONANCE_VAR_apiToken=… or --var apiToken="$API_TOKEN". The command warns on standard error when a variable flagged secret still has no value. Values set by scripts (pm.environment.set, pm.variables.set) carry over to the following requests of the run but are not persisted anywhere.

A request that still contains unresolved {{names}} is sent as-is, as in the app. Pass --strict-variables to fail such a request before it is sent.

Network Options

  • --timeout MS — request timeout, default 30000; 0 disables it
  • -k, --insecure — skip TLS certificate verification
  • --http1 / --http2 — force an HTTP version
  • --no-follow-redirects, --no-cookies — transport switches
  • --proxy URL / --no-proxy — a manual proxy (http://user:pass@host:port, socks5://…) or none. By default the HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables apply, as most CI runners expect
  • --cert FILE --key FILE [--cacert FILE] --cert-host HOST[:PORT] — a client certificate and an extra CA for one host, the equivalent of the certificate settings in the app

Output and Reports

While running, one line per request shows the method, path, status and time, with each test underneath:

Running 3 requests
✓ GET /health 200 23ms
  ✓ status is 200
✗ POST /pets 500 87ms (2 tests failed)
  ✗ created
  ✗ has id
– GET /pets/1 skipped
Passed 1  Failed 1  Skipped 1  (3 requests, 1 iteration, 0.11 s)
Termination: stoppedOnError
  • --junit FILE and --json FILE write the same reports the app exports after a run; directories are created as needed
  • -q, --quiet prints only failures and the summary; -v, --verbose adds script console output and the request and response of every step, with credentials in headers and query strings redacted and bodies cut at 64 KiB
  • Colours are used on a terminal unless --no-color or NO_COLOR is set; diagnostics go to standard error
  • Ctrl+C stops the run, still writes the reports, and exits with code 130

Exit Codes

  • 0 — every request succeeded and every test passed
  • 1 — a request or a test failed, or the run stopped early (stop-on-error, execution limit, invalid branching target)
  • 2 — usage or configuration problem: not a collection, unknown or ambiguous selector, runner not found, bad flag, unreadable file, or the run could not start
  • 130 — interrupted

Pipeline Examples

GitHub Actions

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: db-mobile/resonance@v3.5.1
      - name: Run smoke tests
        env:
          RESONANCE_VAR_apiToken: ${{ secrets.API_TOKEN }}
        run: |
          resonance run collections/petstore --runner smoke \
            --var baseUrl=https://staging.example.com \
            --junit reports/junit.xml
      - uses: actions/upload-artifact@v6
        if: always()
        with:
          name: api-test-report
          path: reports/

GitLab CI

api-tests:
  image: alpine:3.20
  before_script:
    - apk add --no-cache curl
    - curl -fsSL https://raw.githubusercontent.com/db-mobile/resonance/main/install.sh | sh -s -- --version 3.5.0
  script:
    - resonance run collections/petstore --runner smoke --junit reports/junit.xml
  variables:
    RESONANCE_VAR_apiToken: $API_TOKEN
  artifacts:
    when: always
    reports:
      junit: reports/junit.xml

The Linux binary is statically linked, so it runs in minimal images such as Alpine without extra packages. Any other CI system works the same way: install with the one-liner, run with --junit, and publish the report.

Troubleshooting

“open it in Resonance once to convert it”

  • The directory still uses the legacy collection.json layout. Open it in the app once; it is converted to the YAML layout the command reads

“ambiguous request”

  • Several requests share that name. The message lists their file paths; select by path or id instead

Requests reach the wrong host or fail with a proxy error

  • The runner’s HTTP_PROXY/HTTPS_PROXY environment applies by default. Pass --no-proxy to ignore it, or add internal hosts to NO_PROXY

A test passes in the app but fails in CI

  • Compare the variable layers: the app’s active environment is not available to the command unless you export it and pass --env-file, and secrets must be supplied again
  • Run with -v to see the exact request that was sent, with credentials redacted

Next Steps