CLI

CLI in CI/CD

Three commands cover the pipeline side of Routebase: run executes a test suite, scan runs a security scan and gates the build on its findings, and promote records which spec version a deployed environment is actually serving. All three set exit codes, so a pipeline can act on them without parsing output.

This guide assumes the CLI is installed and configured — see CLI Overview, and note the region requirement there if your organization is hosted in the US.

Running a test suite

routebase run <project-id> <suite-id> --environment staging

The project id is the GUID in the app URL. Suite ids come from routebase list suites <project-id> or the suite's page in the app.

Exit code 0 means every test passed, 1 means at least one failed. The run is persisted like any other, so it appears in the suite's History with the same detail you get from a run started in the UI.

Option Effect
--environment, -e Environment name or id — staging works, the GUID works too
--format, -f text (default), json, or junit
--output, -o Write to a file instead of stdout
--iterations, -n Run the suite repeatedly (1–10000)
--delay, -d Milliseconds between iterations (0–60000)
--on-error ignore (default), stop, or abort
--auth-type and friends Override the suite's auth for this run — see below

JUnit output

--format junit writes the XML that most CI systems render as a native test report:

routebase run "$PROJECT_ID" "$SUITE_ID" --environment staging \
  --format junit --output results.xml

Publish results.xml with your platform's test-report step (dorny/test-reporter on GitHub Actions, artifacts:reports:junit on GitLab, PublishTestResults@2 on Azure Pipelines) and failed assertions show up as failed tests rather than as a wall of log output.

Overriding auth for a run

A suite carries its auth configuration in Routebase. When a pipeline holds a fresher credential — a token minted for this build, say — override it per run instead of storing it in the workspace:

routebase run "$PROJECT_ID" "$SUITE_ID" \
  --auth-type bearer --auth-token "$CI_ISSUED_TOKEN"

--auth-type accepts bearer, basic (with --auth-username / --auth-password) and apikey (with --auth-token, plus --auth-header-name, default X-API-Key, and --auth-in header|query). The override applies to this run only and is never persisted.

Running a security scan

routebase scan <project-id> <profile-id> --fail-on critical --format sarif --output routebase.sarif

The command queues the scan profile, polls until it finishes, writes the findings, and sets the exit code from --fail-on. Profiles are built in the app first — the CLI runs an existing profile, it does not create one (Scan profiles).

Option Default Effect
--fail-on critical Fail when an open finding is at or above this severity: none, low, medium, high, critical
--format, -f text text, json, or sarif
--output, -o stdout Write the report to a file
--timeout 600 Seconds to wait before giving up (exit 3)
--poll-interval 5 Seconds between status polls

--fail-on none never fails the build — useful for a report-only rollout where you still want the SARIF upload while the backlog gets triaged.

Give --timeout at least the profile's own Time budget plus queueing time; the default 600 matches the profile default, so a profile configured for longer needs a larger value here.

The gate reads the current open findings for the project, not only the ones this run raised. A finding you marked Accepted risk last week does not come back. That is deliberate — the gate should reflect your posture rather than one scan in isolation.

Everything scan does is also available as three plain REST calls, which is the better fit when you would rather not install a tool on the runner: Security in CI/CD.

Promoting after a deploy

Your pipeline deploys, and Routebase only knows about it if you say so. promote is that statement: it pins a spec version to an environment, so the environment page shows what is actually running there.

routebase promote orders 1.0.0 --env production

Both the spec and the version accept a name or an id — orders and 1.0.0 resolve the same way the app does. --project is required unless you set a default with routebase config set-project.

Put it in the deploy job, after the deployment succeeds. A promotion recorded before the deploy lands is a claim about a state that does not exist yet.

Exit code 5 means one of the three could not be resolved (spec, version, or environment), 6 means the promotion conflicted with the environment's current state — a read-only environment, for instance. See Environments.

A complete GitHub Actions job

name: API Tests

on:
  pull_request:
  workflow_dispatch:

jobs:
  api-tests:
    runs-on: ubuntu-latest
    env:
      PROJECT_ID: 00000000-0000-0000-0000-000000000000 # <-- your project id
      SUITE_ID: 00000000-0000-0000-0000-000000000000   # <-- your suite id
      # US-hosted organizations only; EU needs nothing.
      # ROUTEBASE_REGION: us
    steps:
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: "10.0.x"

      - name: Install the Routebase CLI
        run: dotnet tool install --global Routebase.Cli

      - name: Configure
        run: routebase config set-api-key "$ROUTEBASE_API_KEY"
        env:
          ROUTEBASE_API_KEY: ${{ secrets.ROUTEBASE_API_KEY }}

      # Exits 1 when a test fails, which fails the job.
      - name: Run the suite
        run: |
          routebase run "$PROJECT_ID" "$SUITE_ID" \
            --environment staging \
            --format junit \
            --output results.xml

      - name: Publish the test report
        if: always()
        uses: dorny/test-reporter@v1
        with:
          name: API tests
          path: results.xml
          reporter: java-junit

The same shape works on GitLab CI, Azure Pipelines, Jenkins and Bitbucket — install the tool, configure the key, run the command, act on the exit code. Ready-made snippets for all five live in the app under a suite's CI/CD tab, and copy-paste templates for the security scan are in Security in CI/CD.

Which key the pipeline needs

API keys carry their own permissions and project scopes, narrower than your user account:

Command Needs
run tests:execute plus access to the project
scan security:execute and security:read
promote specs:write plus access to the project
docs pull / push docs:read / docs:write

A 403 on something you can see in the app is almost always the key's scope, not your role.