Metadata-Version: 2.4
Name: bonafide-raas-cli
Version: 0.1.7
Summary: Command-line client for Bonafide RaaS (retrieval-as-a-service): cited answers, agents, skills and MCP tools.
License-Expression: Apache-2.0
Project-URL: Documentation, https://github.com/skyeglobal-ai/bonafide-raas/tree/main/clients
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.31
Requires-Dist: keyring>=25
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == "aws"
Dynamic: license-file

# 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

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

Add the AWS extra only if you use `RAAS_CREDENTIALS_SECRET`:

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

## Validate an install

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

```bash
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:

```powershell
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

```bash
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:

```bash
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

| Symptom | Likely cause |
|---|---|
| `401 Unauthorized` | Token missing, expired, issued by the wrong Keycloak realm, or without a `client_id` claim. Sign in again, or ask your administrator to check the client's token settings |
| `401` after setting `RAAS_TOKEN` | The value includes `Authorization:` or `Bearer`. Set the bare token |
| Exit code `3` | No credentials set. See the table above |

## Use

```bash
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.
