bonafide-raas-cli

Command-line client for Bonafide RaaS (retrieval-as-a-service). It returns cited answers from the Bonafide catalog, runs the multi-agent answer path, runs named skills, and calls the MCP tools. The CLI is a thin client over the REST API, so it holds no secrets of its own.

Install

pipx install bonafide-raas-cli          # or: pip install bonafide-raas-cli
raas --help

Add the AWS extra only if you use RAAS_CREDENTIALS_SECRET:

pipx install "bonafide-raas-cli[aws]"

Validate an install

Run these in order. Each line says what a correct result looks like.

raas --version                       # prints raas <version>
raas use qa                          # {"environment": "qa", "source": "saved", ...}
raas doctor                          # JSON; "api_reachable" ok; exit 0 once you have credentials
raas qa health                       # {"status": "ok"}, exit 0 (needs no sign-in)
raas qa login                        # prints a link and code; approve it in the browser
raas qa retrieve "What is check-in time?"   # cited answer, exit 0 (see "If retrieve fails")
raas logout                          # {"profile": "default", "signed_out": true}
raas bogus                           # usage error, exit 2

If retrieve fails

• 401 AUTHENTICATION_FAILED after a good sign-in: the signed-in person has no api_keys record. An administrator adds one with principal: "person", keyed by your Keycloak sub (see docs/RaaS-Config-Reference.md).
• 401 unauthorized_client from raas with a credentials secret: the client is not configured for client credentials in Keycloak.
• A 502 after a long wait: the request ran past the API's time limit. Retry, or ask for a narrower query.

Automated checks

The CLI, skill and REST contract tests run in CI (.github/workflows/ci.yml). The install check runs on macOS, Linux and Windows (.github/workflows/cli-install.yml). The live checks above need a network and, for retrieve, a sign-in.

Windows

Install with the Python launcher, then pipx:

py -m pip install --user pipx
py -m pipx ensurepath          # then open a new terminal
pipx install bonafide-raas-cli
raas --version

Set environment variables in PowerShell with $env:NAME = "value", for example $env:RAAS_TOKEN = "...". The commands are the same on every platform: raas use qa, raas qa login, raas doctor.

The CLI keeps its files under ~/.config/raas on macOS and Linux, and under %APPDATA%\raas on Windows: settings.json for raas use and profiles.json for profiles.

Your sign-in from raas login is stored in the OS keyring (macOS Keychain, Windows Credential Manager, or the Secret Service on Linux). Where no keyring is available, it's stored in a file, <profile>/token.json, which is readable only by you on macOS and Linux and protected by your profile's permissions on Windows. Set RAAS_AUTH_STORAGE=plaintext to use the file deliberately. raas logout forgets the sign-in for a profile, in the keyring and the file.

Check your setup

raas doctor            # report prerequisites and configuration (JSON; exit 0 when all required checks pass)
raas doctor --fix      # also install missing Python packages, asking first
raas doctor --fix --yes   # install without asking

doctor checks the Python version, that raas is on your PATH, the API URL and that it answers, your credentials (a token, client credentials, a cached raas login), the Keycloak issuer, and the boto3 package that RAAS_CREDENTIALS_SECRET needs. --fix installs only boto3, and only when a credentials secret is configured. It never installs Python itself or pipx: doctor reports those with the command to run.

Configure

Set the default environment once per machine:

raas use qa               # QA is the default from now on
raas login                # signs in to QA
raas use                  # shows the current default
raas use --reset          # back to prod

For one command, name the environment first: raas dev health, or raas prod login. RAAS_ENVIRONMENT overrides the saved default for a shell or a CI job. With nothing set, the default is prod. A raas use default is stored in ~/.config/raas/settings.json.

Built-in environments supply the API URL, the Keycloak issuer and the raas-cli client ID. Your credentials secret, environment variables and ~/.config/raas/profiles.json override them, in that order: environment variable, profile, credentials secret, built-in values.

Authentication

The API checks the bearer token at the gateway before any request reaches the service. The token must be a Keycloak access token issued to a client, and it must carry a client_id claim. A token without that claim is rejected with 401 Unauthorized.

Troubleshooting

Use

raas health                                            # no credentials needed
raas retrieve "Which hotels are in New York City?"     # cited answer
raas retrieve "..." --mode sources                     # full source records
raas agent "..."                                       # multi-agent answer; read misalignment_flags
raas skills list
raas skills run facts "..."
raas mcp tools
raas mcp call retrieval_search --args '{"query": "..."}'
raas job <job_id>

Output is JSON on stdout. Exit codes: 0 success, 1 API error (details on stderr), 2 usage error, 3 missing configuration.

Changes

0.1.3 (release pending): The CLI identifies itself to the API with the X-RaaS-Client header, so usage can be reported by channel. No behaviour change for users.

0.1.2: Added raas --version, which prints the installed version.

0.1.1: The API accepts a bearer token alone. RAAS_API_KEY is optional and no longer required, so existing configurations keep working. Added the Authentication and Troubleshooting sections.

0.1.0: First public release.

Compatibility

The version follows semantic versioning. A breaking change to the API contract is released as a new major version. Before 1.0, minor versions may still include breaking changes; each release notes them.

Support

Report problems with the command, its version (raas --version), and the exit code. Do not send API keys, tokens or secret names.

License

Apache License 2.0. See LICENSE. This license covers the CLI code only; use of the RaaS service and its data is governed by your service agreement.