Cloud

Cloud keeps a copy of your collection where your team and your customers can open it. Git stays the source of truth. Your CI publishes the folder on every push, and Cloud shows the latest version.

• Publish a folder of YAML files from CI with curl-runner publish.
• Share it with a link, or with named people.
• Pull a shared collection onto your machine with curl-runner pull.

What leaves your machineCopy Anchor Link

Publishing sends the YAML files in the folder, the cloud: name, description and inputs, and the git commit, ref and repository when your CI provides them. That is all.

Secret values never leave your machine. A secret input is declared by name only. Its value is set by whoever runs the collection, on their own machine. publish refuses to send a folder where a secret input has a literal value in a variables block (global, collection or top level).

Files over 1 MiB, and folders over 2,000 files or 25 MiB, are refused.

Declare the collectionCopy Anchor Link

Add a cloud: block to curl-runner.yaml in the collection folder:

cloud:
  collection: payments-api
  name: Payments API
  description: Smoke tests for the payments service.
  inputs:
    - name: BASE_URL
      description: Where the API runs.
      default: https://api.example.com
    - name: API_TOKEN
      description: A token for the staging API.
      secret: true
      required: true

Each input has these keys:

If a non-secret input has no default, the value of the variable with the same name in collection.variables or global.variables is used.

Publish from CICopy Anchor Link

curl-runner publish

payments-api: published v3 (1 added, 2 changed, 0 removed)

publish checks every file on your machine first and sends nothing if anything is wrong. An unchanged folder is not published again:

payments-api: unchanged (v3)

curl-runner publish [DIR...] [--collection <slug>] [--team <slug>] [--server <url>] [--dry-run]

The token comes from CURL_RUNNER_TOKEN, or from the session that curl-runner login saved. A publish token (crt_...) belongs to one team, so you must give it a team. A signed-in account that is in one team needs no --team.

Publishing records the commit, ref and repository from GitHub Actions or GitLab CI, so each version links back to git.

Exit codesCopy Anchor Link

publish tries a request up to five times, waiting longer each time, before it exits with 5.

With more than one folder, a refusal from the server for one folder does not stop the others. Each failure is printed with its collection, and the exit code is the most severe one: 5, then 2, 4, 3, 1. An unreachable server stops the run at once.

A config file named .curl-runner.yaml is not published, so publish stops with exit 1 and asks you to rename it to curl-runner.yaml.

login, logout, publish and pull all exit 1 for a bad option, a missing value or a bad --server. Exit 2 is only for sign-in problems.

GitHub ActionCopy Anchor Link

The repo ships a composite action that installs the CLI and runs publish.

name: Publish to curl-runner Cloud

on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: alexvcasillas/curl-runner/actions/publish@main
        with:
          token: ${{ secrets.CURL_RUNNER_TOKEN }}
          team: acme
          path: collections/*
          version: 2.5.0

Any other CI works the same way. Install the CLI, set CURL_RUNNER_TOKEN and CURL_RUNNER_TEAM, and run curl-runner publish.

Create a teamCopy Anchor Link

An account that isn't in a team can't publish. Create one with a signed-in session. This reads the session curl-runner login saved:

SESSION=$(jq -r '.servers["https://api.curl-runner.com"].session' ~/.config/curl-runner/credentials.json)
curl -X POST https://api.curl-runner.com/v1/teams \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"slug": "acme", "name": "Acme"}'

On a self-hosted server, SIGNUP decides who can do this. See Self-hosting.

Share a collectionCopy Anchor Link

Each collection has a share link and an access mode: off, public or restricted. In restricted mode only the people on the access list can open the link. Restricted sharing needs the Team plan.

curl -X PATCH https://api.curl-runner.com/v1/teams/acme/collections/payments-api/share \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"access": "restricted"}'

Use "public" instead to let anyone with the link open it. The reply has the link:

{
  "access": "restricted",
  "link": "https://cloud.curl-runner.com/s/<token>",
  "expires_at": null,
  "entries": []
}

PATCH also takes expires_in_days (null removes the expiry) and reset_link: true, which replaces the link and stops the old one working.

Then add people to the access list. An entry is an email, or *@example.com for everyone on a domain. notify sends an invite email, and only to email entries that are new:

curl -X POST https://api.curl-runner.com/v1/teams/acme/collections/payments-api/share/entries \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"entry": "dev@example.com", "notify": true}'

GET on the same /share path shows the link and the list. DELETE on /share/entries/<entry> removes someone.

Publish tokensCopy Anchor Link

A publish token belongs to one team and can only publish. Create one as a signed-in member:

curl -X POST https://api.curl-runner.com/v1/teams/acme/tokens \
  -H "Authorization: Bearer $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name": "github-actions"}'

The reply shows the token once. Copy it into your CI's secrets. Add expires_in_days to make it expire, and DELETE /v1/teams/acme/tokens/<id> to revoke it.

Pull a shared collectionCopy Anchor Link

If someone shared a collection with you, pull it:

curl-runner pull https://cloud.curl-runner.com/s/<token> payments-api

Pulled Payments API v3 into payments-api. Fill in payments-api/.env (see .env.example), then run: cd payments-api && curl-runner --all

The files are written into the folder. Pulled secret inputs are listed in .env.example without values. Copy it to .env and fill them in. Run the collection from inside the folder, so its .env and curl-runner.yaml are used and nested folders are included.

To get the latest version later, run pull in that folder:

curl-runner pull payments-api

Updated Payments API to v4.

If you changed a pulled file, pull asks before replacing it. Without a terminal, it stops and tells you to pass --force.

curl-runner pull [LINK] [DIR] [--force]

A share link can also look like curl-runner://open?server=<api-url>&share=<token>. It names the server itself, so pull doesn't have to look it up. Use it for a self-hosted server.

A collection that isn't public asks you to sign in. Run curl-runner login --server <url> first, or let pull offer it in a terminal. A pull writes nothing until every file passes the same path checks publish uses, so a bad bundle can't write outside the folder. Exit codes: 0 ok, 1 a problem with the link, the data or an option, 2 sign-in, 5 the server can't be reached.

Next stepsCopy Anchor Link