CLI

CLI Overview

The Routebase CLI is a command-line client for your workspace. It runs test suites and security scans, promotes spec versions after a deploy, and syncs documentation to and from Markdown files — all with the same permissions your API key carries.

It is a client, not a standalone tool: everything it does happens in your Routebase workspace, and it needs an account and an API key. There is no offline mode and no local test engine.

Not to be confused with the MCP server (routebase-mcp), which connects AI agents to your workspace over stdio. Different tool, different install, different job — see MCP Quickstart.

Install

The CLI ships as a .NET global tool and needs the .NET 10 runtime on the machine:

dotnet tool install --global Routebase.Cli

The installed command is routebase. Upgrade later with dotnet tool update --global Routebase.Cli.

Most CI images that already build .NET code can run it as-is. On GitHub Actions, add actions/setup-dotnet with dotnet-version: "10.0.x" before the install step.

Configure

Create an API key under Settings → API Keys (API Keys), then point the CLI at your workspace:

routebase config set-api-key "rb_live_…"
routebase config set-region us          # US-hosted organizations only
routebase config set-project <project-id>   # optional default for commands that take one
routebase config show

Settings are stored in ~/.routebase/config.json. config show prints the current state with the key truncated, which is the fastest way to answer "why is it talking to the wrong place".

Command Sets
config set-api-key <key> The API key every request authenticates with
config set-url <url> The API base URL. Defaults to https://api.routebase.dev; change it only for a self-hosted deployment
config set-region <us|eu> The region your organization is hosted in — see below
config set-project <id> A default project, so promote works without repeating --project
config show Prints the effective configuration

Region

If your organization is hosted in the US, the CLI needs to be told. One host serves both regions, and the browser app picks the region from a cookie. A CLI sends no cookie, so without a region signal your requests are served from the EU region — where a US organization's API key does not exist. The run then fails at authentication, which points nowhere near the real cause.

Two ways, and the environment variable wins when both are set:

routebase config set-region us     # persisted in ~/.routebase/config.json
export ROUTEBASE_REGION=us         # per-shell or per-pipeline; takes precedence

In CI prefer the variable — a pipeline has no config file to carry over between jobs. config show marks the value as (from ROUTEBASE_REGION) when the variable is what took effect.

EU-hosted organizations need nothing. Check your region under Settings → Organization; see Region selection.

A value other than us or eu in ROUTEBASE_REGION is ignored rather than rejected. That is deliberate: a pipeline referencing an undefined variable hands through the literal ${ROUTEBASE_REGION}, and that must not become a request header. Typing an unknown region into config set-region does fail, with exit code 2 — a typo you made by hand is worth reporting.

Exit codes

Every command sets an exit code, which is what makes the CLI useful in a pipeline.

Code Meaning
0 Success
1 The run failed — tests failed, or an open finding tripped --fail-on
2 Configuration error: no API key, an unknown region, an invalid flag
3 Network error, or the run did not finish (timed out, failed, cancelled)
4 Authentication error — the key is wrong, or lacks the permission or project scope
5 Project, suite, profile, spec, version or environment not found
6 Conflict — a documentation page changed remotely since docs pull

Note the difference between 1 and everything above it: 1 means Routebase did its job and the answer was negative. 3 and 4 mean the job never happened. A pipeline that treats every non-zero code the same will report infrastructure problems as test failures.

Commands

Command Guide
routebase run CLI in CI/CD
routebase scan CLI in CI/CD
routebase promote CLI in CI/CD
routebase docs pull / docs push Docs as Code
routebase list suites <project-id> Lists the test suites in a project, with their ids

routebase <command> --help prints the full option list for any of them.

Troubleshooting

No API key configured. — Run routebase config set-api-key. In CI, remember that each job starts with a fresh home directory: the config command has to run in the same job as the command that uses it, or you pass the key some other way.

Authentication fails although the key is correct. — Almost always the region. Run routebase config show and check the last line. A US-hosted organization without a region signal gets exactly this error.

403 on a project you can see in the app. — API keys carry their own project scopes and permissions, which are narrower than your user account's. Check the key under Settings → API Keys.

You must install or update .NET to run this application. — The tool found a .NET installation without the 10.0 runtime. This happens when .NET was installed somewhere the launcher does not look by default (a Homebrew install on macOS, for example). Point DOTNET_ROOT at the right one:

export DOTNET_ROOT=/usr/local/share/dotnet

A run works locally and fails in CI. — Compare routebase config show in both places. The usual differences are the region, the API key's project scope, and an environment whose base URL is reachable from your laptop but not from the runner.