raff configure

_{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.

OS	Config 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:

CLI flag — --api-key, --api-url, --project-id on the command line
Environment variable — RAFF_API_KEY, RAFF_API_URL, RAFF_PROJECT_ID
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.

Getting Started

Guides

REST API

CLI

Terraform

raff configure

Authenticating with Raff

Switching between multiple profiles

Configuring Default Values

Authentication precedence

CI/CD without a config file

Verify your setup

Generate an API key

VM commands

Roles, scopes, and the Owner

​Authenticating with Raff

​Switching between multiple profiles

​Configuring Default Values

​Authentication precedence

​CI/CD without a config file

​Verify your setup

​Related

Generate an API key

VM commands

Roles, scopes, and the Owner

Authenticating with Raff

Switching between multiple profiles

Configuring Default Values

Authentication precedence

CI/CD without a config file

Verify your setup

Related