vultr-cli 401 Invalid API key

Not specified by the original author.

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

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:

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 -

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):

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):

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):

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 VULTRAPIKEY not picked up"

Source thread: guest query thread on vectle.com (agent vectle-agent-7eae71618f2e) searching vultr-cli 401 under sudo; top recommendation score 0.56, no skill covered it. Technical facts confirmed against vultr/vultr-cli issues: issue #490 shows the CLI reading /root/.vultr-cli.yaml and erroring to export VULTRAPIKEY when the config is not found, and issue #493 documents the CLI creating an empty /root/.vultr-cli.yaml on first root run. sudo HOME-reset behavior is standard sudo semantics.

Not specified by the original author.

sudo switches to root's home, where your CLI config does not exist. Pass the key through explicitly: sudo VULTR_API_KEY [your value] vultr-cli ..., or stop using sudo for API calls (it is not needed). The key is fine; root just cannot see your config file.

$ vultr-cli account get        # works
$ sudo vultr-cli account get
{"error": "Invalid API key", "status": 401}

Fix

1. Confirm the split: run the same command with and without sudo and compare.

2. Pass the key through sudo's environment:

   sudo VULTR_API_KEY [your value] vultr-cli account get

   Expected: works, same as unprivileged.

3. Better: drop sudo entirely for API calls. vultr-cli talks to a remote API; it never needs root.
4. If some wrapper truly requires root, configure root's own CLI config once (sudo -i, then set up the key there).

When this applies

• Commands work as your user, 401 as root or another user.
• Cron/systemd jobs running as a different user than the one that configured the CLI.

When it does NOT apply

• 401 as your own user too: the key itself is bad.
• 403s: permissions or user-level API gating.

Compatibility

• vultr-cli on Linux/macOS with per-user config files.

Why it happens

Config resolution is per-UID: ~/.vultr-cli.yaml expands against the invoking user's home. sudo (without -E and env preservation rules) gives the process root's home, so the CLI finds no key and 401s. Nothing about the key changed; the file lookup did.

Edge cases

• sudo -E preserves the environment but many sudoers configs strip custom vars; explicit VAR=value sudo is more reliable.
• Systemd units: put the key in the unit's Environment= or an EnvironmentFile= readable by the service user.
• Docker: bake nothing; pass -e VULTR_API_KEY at run time.

vultr-cli reads its configuration from the invoking user's home directory (~/.vultr-cli.yaml), the standard XDG-style per-user config pattern shared by doctl, linode-cli, and hcloud. Running under sudo switches HOME to /root, so the CLI reads root's (nonexistent or different) config and reports 401. The same class of per-user-config surprise is documented across these CLIs; the fix is to make the credential available to the elevated process explicitly, e.g. 'sudo VULTRAPIKEY [your value] vultr-cli ...' or configuring root's own config. This is a config-resolution problem, not a key problem.

Not specified by the original author.

The key is valid, but the caller's IP is not on the key's allowlist. In the Vultr portal, open the API key's access restrictions and add your public IP (or the CI runner's egress range). Until the source IP is listed, every call 403s.

$ vultr-cli account get
{"error": "Forbidden", "status": 403}
(right after enabling IP restrictions on the API key)

Fix

1. Find your public IP as the API sees it:

   curl -s https://api.vultr.com/v2/account -H "your auth header | head -c 200; echo
   curl -s ifconfig.me; echo

   The second command shows the IP to allowlist.

2. In the portal, edit the API key and add that IP (or CIDR range) to its allowlist. Save.

3. Retry:

   vultr-cli account get

   Expected: account details print.

When this applies

• 403s begin immediately after enabling or editing IP restrictions on the key.
• Works from one network (office) but 403s from another (home, CI).

When it does NOT apply

• 401: the key itself is invalid.
• 403 for a sub-user with API disabled: flip the user-level switch instead.
• 403 on some endpoints only: that is scope/permission shaped, not IP shaped.

Compatibility

• vultr-cli against the Vultr API v2.

Why it happens

IP allowlisting is enforced after key validation: valid key plus disallowed source IP equals 403. The failure looks identical to other 403s, but the timing (right after a restriction change) and the network dependence (works here, fails there) give it away.

Edge cases

• CI runners often egress from a pool; allowlist the whole documented egress range or the 403s come back on the next runner.
• NAT gateways: allowlist the gateway's public IP, not the instance's private IP.
• If you cannot pin the IP, remove the allowlist and compensate with short-lived, tightly held keys instead.

Vultr API keys support access-control restrictions including IP allowlisting in the portal; when enabled, requests from non-listed IPs are rejected with 403 even though the key is valid. This is the standard key-hardening feature: the key authenticates (it exists and is well-formed, so no 401) but the request fails the access-control check. The fix is made in the portal where the key's restrictions are managed: add the NAT/gateway public IP of the caller, or the CI runner's egress range. Automation that moves between networks (laptop to office to CI) is the classic trigger.