## TL;DR

`vultr-cli` reads its API key from `$HOME/.vultr-cli.yaml`. When you run it under `sudo`, `HOME` becomes `/root`, so the CLI looks at `/root/.vultr-cli.yaml` instead of your user's config, finds nothing, and every command fails with 401 Unauthorized. Fix it with one of these: run with `sudo -E` so your home and environment carry over, copy your config to `/root/.vultr-cli.yaml` with mode 600, or pass the key inline as `sudo VULTR_API_KEY [your value] api key] vultr-cli account`.

### Verbatim error

```text
Error:
Please export your VULTR API key as an environment variable or add 'api-key' to your config file, eg:
export VULTR_API_KEY [your value]
```

With a missing or empty key, API calls then return `401 Unauthorized` and vultr-cli exits with code 4 (authentication failure).

## When this applies

- You ran `vultr-cli` as your normal user and it worked, but the same command under `sudo` fails with 401 or the "add api-key to your config file" error.
- `sudo vultr-cli account` created a mysterious empty `/root/.vultr-cli.yaml` file (vultr-cli does this on first run as root instead of erroring cleanly).
- You installed vultr-cli system-wide (e.g. `/usr/local/sbin/vultr-cli`) and now scripts or automation running as root cannot authenticate.

## When this does NOT apply

- A 401 on a non-sudo command: the key itself is wrong, expired, or lacks the needed scope. Regenerate it in the Vultr control panel under API.
- `401 Unauthorized IP address`: Vultr restricts the key to allowed IPs. The caller's IP is not on the allowlist, fix that in the control panel, not on the CLI side.
- 403 errors: a scope/permission problem, not a missing config.

## Diagnose

1. Confirm which home directory sudo is using:

```bash
sudo sh -c 'echo $HOME'
```

Expected output: `/root`. That is why your user config is not read.

2. Confirm the user's config exists and has a key -

```bash
ls -la ~/.vultr-cli.yaml && grep -c '^api-key value ' ~/.vultr-cli.yaml
```

Expected: the file exists and the grep prints `1`. If the file is missing, you never configured vultr-cli for this user; see step 1 of the fix below instead.

## Fix: pick one

1. Preserve your environment with `sudo -E` (quickest, no files changed):

```bash
sudo -E vultr-cli account
```

Expected: `sudo -E` keeps `HOME` pointing at your home directory, so the CLI finds your existing `~/.vultr-cli.yaml`. Note the calling shell must already have `VULTR_API_KEY` exported if the config relies on the env var instead of the file.

2. Copy the config to root's home (best for cron/CI where `sudo -E` is unavailable):

```bash
sudo cp ~/.vultr-cli.yaml /root/.vultr-cli.yaml
sudo chmod 600 /root/.vultr-cli.yaml
```

Expected: `sudo vultr-cli account` now authenticates. Mode 600 keeps the key readable only by root.

3. Pass the key inline (one-off, avoids touching config files):

```bash
sudo VULTR_API_KEY [your value] api key] vultr-cli account
```

Expected: the command authenticates. The key stays out of root's config; it is visible in the process list briefly, so prefer option 1 or 2 for repeated use.

Verify any fix with `sudo vultr-cli account`, which prints your account info and exits 0 on success.

## Root cause

vultr-cli resolves its config path from the `HOME` environment variable (`$HOME/.vultr-cli.yaml`). sudo resets `HOME` to `/root` by default, so the CLI reads a different config file than the one you set up. A missing key means the API requests go out without credentials, and the Vultr API answers 401.

## Edge cases

- Related bug (vultr-cli v3.4.0): `--config /path/to/file.yaml` is ignored and the CLI still tries `$HOME/.vultr-cli.yaml`. If you hit this, use the `VULTR_API_KEY` env var approach instead of `--config`.
- Running as root on first use writes an EMPTY `/root/.vultr-cli.yaml`. An empty file does not error at read time; the CLI just proceeds with no key and 401s. Delete or replace it before applying the fixes above.
- `sudo -E` is blocked by some sudoers configurations (`SETENV` not allowed). Use option 2 or 3 then.
- On systems where root's home is not `/root`, check the actual home with `sudo sh -c 'echo $HOME'` before copying.

## Tool and version compatibility

- vultr-cli v3.x (the `$HOME/.vultr-cli.yaml` behavior and the 401 message are confirmed on v3.4.0; the sudo HOME reset applies to all v3 releases).
- Linux and macOS sudo behavior. Not applicable to Windows.

## Variant phrasings

- "vultr cli 401 unauthorized when using sudo"
- "vultr-cli asks for api key under sudo but config exists"
- "Error Reading in file: /root/.vultr-cli.yaml"
- "vultr-cli sudo VULTR_API_KEY not picked up"