Skip to main content
Updated May 10, 2026 raff configure walks you through writing a YAML config at ~/.raff/config.yaml (%USERPROFILE%\.raff\config.yaml on Windows). The CLI reads this on every command unless overridden by environment variables or per-command flags.

​
Authenticating with Raff

To use raff, you need an API key. Generate one in the dashboard at rafftechnologies.com under Team & Projects → API Keys. Run the configure command to set up a profile: 
raff configure
You’ll be prompted for three fields, each with the existing value as the default (just press Enter to keep it): 
API URL [https://api.rafftechnologies.com]:
API Key [...]: raff_pub_xxx
Default Project ID (optional) [...]: 11111111-2222-3333-4444-555555555555
When you finish, you’ll see: 
Profile "default" saved to /home/you/.raff/config.yaml
The active profile becomes the one you just configured. Subsequent raff commands read credentials from this file.
configure does not currently validate the key against the API — it just saves to disk. The first real call (e.g. raff project list) will surface an auth error if the key is wrong.

​
Switching between multiple profiles

raff supports multiple profiles in the same config file so you can keep separate keys (e.g. staging vs production): 
raff configure                    # writes/updates the "default" profile
raff configure --profile staging  # writes/updates the "staging" profile and makes it active
raff configure --profile default  # switch back to "default" (just press Enter through the prompts)
Other commands (vm list, vpc list, …) do not take a --profile flag — they always use whichever profile is set as current-profile in ~/.raff/config.yaml. To use a non-active profile for a single command, override with environment variables: 
RAFF_API_KEY=raff_pub_yyy RAFF_PROJECT_ID=<staging-project-uuid> raff vm list
Or with command-line flags: 
raff vm list --api-key raff_pub_yyy --project-id <staging-project-uuid>

​
Configuring Default Values

The raff configuration file stores your API key and default values for command flags. The file is created automatically the first time you run raff configure.
OSConfig path
Linux~/.raff/config.yaml
macOS~/.raff/config.yaml
Windows%USERPROFILE%\.raff\config.yaml
The file ends up looking like: 
current-profile: default
profiles:
  default:
    api_url: https://api.rafftechnologies.com
    api_key: raff_<your-prod-key>
    project_id: <your-prod-default-project-id>
  staging:
    api_url: https://api.rafftechnologies.com
    api_key: raff_<your-staging-key>
    project_id: <your-staging-default-project-id>
You can edit it directly if you prefer — current-profile selects which profile every command (other than configure) uses.

​
Authentication precedence

Every command resolves credentials in this exact order:
  1. CLI flag — --api-key, --api-url, --project-id on the command line
  2. Environment variable — RAFF_API_KEY, RAFF_API_URL, RAFF_PROJECT_ID
  3. Config file — the profile named in current-profile in ~/.raff/config.yaml
If a credential isn’t set in any of those, the command fails with a clear error. The CLI never prompts for credentials mid-command — that’s a one-time configure thing.

​
CI/CD without a config file

For CI/CD where there’s no interactive shell, env vars work without configuring anything: 
export RAFF_API_KEY="raff_<your-key>"
export RAFF_API_URL="https://api.rafftechnologies.com"
export RAFF_PROJECT_ID="<your-default-project-id>"

raff vm list

​
Verify your setup

raff project list
If this returns a project list, you’re authenticated correctly. If it errors with 401 Unauthorized, double-check the API key. If it errors with 403 Forbidden, the key is valid but doesn’t have account.projects.view permission — see the role assigned to the key on the API Keys page.

Generate an API key

Get the key you need before configuring.

VM commands

Start using the CLI.

Roles, scopes, and the Owner

Why you may see a 403 even with a valid key.
Last modified on May 11, 2026