Docs / Everywhere else

CLI

Send requests from your terminal and run collections in CI. One binary, no runtime required.

flow is a single executable for macOS, Linux and Windows. It sends requests from the machine it runs on, and runs the collections already in your workspace.

Installing#

Download the binary for your platform.From the CLI release. There is no runtime to install.

chmod +x flow-0.1.0-darwin-arm64
sudo mv flow-0.1.0-darwin-arm64 /usr/local/bin/flow
flow --version

Or use npm, if you already have Node 20+.
```
npm install -g @arythmatic/flow-cli
```

Sending a request#

No account or configuration needed for this. curl's spellings are reused where curl has one — -H, -d, -i, -k, -o, --fail.

flow get https://api.example.com/users
flow post https://api.example.com/users --json '{"name":"Ada"}'
flow get localhost:3000/health          # your machine, not a server
flow get localhost:8080/x -n 50         # min / median / p95 / max
flow get api.example.com/x --dry-run    # exactly what would be sent

Connecting your workspace#

Create an API key.Workspace → Team → API Keys.
Run flow login and paste it.The key identifies the workspace on its own — there is nothing else to look up. It is stored with mode 0600.
```
flow login
```
Check it worked.
```
flow whoami
flow ls
```

Running a collection#

Every request in order, folders included, sent from this machine — with assertions and scripts, executed by the same modules the server uses.

flow run Payments --env Staging

Payments · 4 request(s) · sent from this machine

  ✓ create charge                201 Created · 84 ms
      ✓ Status eq 201
      ✓ JSONPath $.id exists
  ✗ refund                       200 OK · 61 ms
      ✓ Status eq 200
      ✗ JSONPath $.state eq refunded
        expected "refunded", got "pending"

1 of 4 failed  ·  5/6 assertions passed

200 is not a pass

The second request returned 200 and still failed, because an assertion did not hold. The run exits non-zero, which is what CI reads.

In CI#

- name: Install flow
  run: |
    curl -sSLo /usr/local/bin/flow \
      https://github.com/askmeidentitycorp/flowapi-releases/releases/download/cli-v0.1.0/flow-0.1.0-linux-x64
    chmod +x /usr/local/bin/flow

- name: API smoke tests
  run: flow run "Smoke tests" --env Staging
  env:
    FLOW_API_KEY: ${{ secrets.FLOW_API_KEY }}

What it does not do yet#

Runs are not written back to history or collection-run reports
No chaining between requests with {{request.field}}
Requests run sequentially
gRPC requests are skipped; the Windows binary is unsigned

Frequently asked questions#

Does the CLI need Node.js?

No. The released binaries bundle everything they need and run on a machine with no runtime installed, including a slim CI image. An npm package is available if you already have Node 20 or newer.

Can the CLI run API tests in CI?

Yes. flow run executes every request in a collection with its assertions and scripts and exits non-zero if any fail. The only secret it needs is a workspace API key.