> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafftechnologies.com/llms.txt
> Use this file to discover all available pages before exploring further.

# raff configure

> Authenticate the CLI and set default values. Stores credentials in ~/.raff/config.yaml; supports multiple profiles, env-var overrides, and per-command flag overrides.

<sub>Updated May 10, 2026</sub>

`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](https://rafftechnologies.com) under **Team & Projects → API Keys**.

Run the configure command to set up a profile:

```bash theme={null}
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.

<Note>
  `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.
</Note>

## Switching between multiple profiles

`raff` supports multiple profiles in the same config file so you can keep separate keys (e.g. staging vs production):

```bash theme={null}
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:

```bash theme={null}
RAFF_API_KEY=raff_pub_yyy RAFF_PROJECT_ID=<staging-project-uuid> raff vm list
```

Or with command-line flags:

```bash theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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](/products/manage/team-projects/quickstart-guides/generate-api-key) page.

## Related

<CardGroup cols={3}>
  <Card title="Generate an API key" icon="key" href="/products/manage/team-projects/quickstart-guides/generate-api-key">
    Get the key you need before configuring.
  </Card>

  <Card title="VM commands" icon="server" href="/reference/cli/vm">
    Start using the CLI.
  </Card>

  <Card title="Roles, scopes, and the Owner" icon="lightbulb" href="/products/manage/team-projects/concepts/roles-and-api-keys">
    Why you may see a 403 even with a valid key.
  </Card>
</CardGroup>