Skip to content
Start free

CLI

CLI Authentication

Authenticate the kubeadapt CLI with an API key: interactive login, environment variables, or flags. Includes exit codes and a CI example.

Last updated

kubeadapt authenticates to the Kubeadapt API with a bearer token. Create an API key under Settings → API Keys at app.kubeadapt.io, then save it with kubeadapt auth login, set KUBEADAPT_API_KEY, or pass --api-key.

Login

Run auth login to store your API key:

bash
kubeadapt auth login

The command prompts for your API key (input is hidden). You can skip the prompt by passing the key directly:

bash
kubeadapt auth login --api-key ka_your_key

auth login checks the key against the API before it writes anything. On success it prints Authenticated. API key saved to <path>. with the config file it wrote; see Configuration for where that file lives. If the API rejects the key, nothing is written and your existing credentials stay as they were.

Check status

To check which credentials the CLI will use (after flags and environment variables are applied) and whether the API accepts them:

bash
kubeadapt auth status

The API key is masked in the output:

plaintext
API URL:    https://public-api.kubeadapt.io
API Key:    ka_y..._key
Status:     Connected
Org:        Acme (org-id)
Request ID: 6f411a29-2070-4dac-99e4-cbfd2c39e14d

auth status calls the API, and exits 0 only when the key is accepted, so you can use it as a gate in scripts. -o json returns api_url, api_key_masked, status, org_name, and org_id.

Logout

To remove the stored API key from the config file:

bash
kubeadapt auth logout

This clears the api_key field in the config file. The file itself is not deleted.

Using environment variables

For CI/CD pipelines or scripts where you don't want to write a config file, set KUBEADAPT_API_KEY (and KUBEADAPT_API_URL if you need a non-default endpoint). See Configuration: Environment variables for the full list.

bash
export KUBEADAPT_API_KEY=ka_your_key
kubeadapt get clusters

Using flags

You can pass credentials directly on any command with --api-key and --api-url:

bash
kubeadapt --api-key ka_your_key get clusters

Exit codes

CodeMeaning
0Success
2Usage error: bad flag, argument, or value, a flag the endpoint does not accept (such as --cost-mode on get clusters), or a --config file that does not exist; nothing was sent to the API
1Any other failure: API, network, or authentication errors, or partial paginated results

An API rejection such as HTTP 400 or 422 exits 1, because the request was sent. Codes 3 to 125 are unassigned, so treat any non-zero code other than 2 as a generic failure.

GitHub Actions example

yaml
1- name: Check pending recommendations
2  env:
3    KUBEADAPT_API_KEY: ${{ secrets.KUBEADAPT_API_KEY }}
4  run: |
5    kubeadapt auth status
6    kubeadapt get recommendations --status pending -o json

Store KUBEADAPT_API_KEY in your repository's encrypted secrets. Never hardcode API keys in workflow files.

Troubleshooting

ErrorCauseFix
Authentication failed: API key is invalid or expired.Invalid, expired, or revoked API keyCreate a new key at app.kubeadapt.io and run kubeadapt auth login
invalid API key: rejected by <url>. Nothing was written; ...auth login was given a key the API rejectedCheck the key. On v0.2.1 or earlier, also pass --api-url https://public-api.kubeadapt.io
no API key configured. Run 'kubeadapt auth login' firstNo key in flags, environment, or config file, or the config file could not be readRun kubeadapt auth login or set KUBEADAPT_API_KEY
Access denied: you don't have permission for this resource.The key lacks the scope this command needs, or the cluster is outside the key's allow-listCheck the key's scopes under Settings → API Keys
Cannot connect to Kubeadapt API: connection refused.Wrong API URL or a network problemRun kubeadapt auth status and check the API URL
cannot save credentials: ... permission deniedYour user cannot read or write the config file (for example, it was created with sudo)Fix the ownership with chown $USER <path>, then chmod 0600 <path>. kubeadapt --help shows the path