vultr-cli 401 sudo config file

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 API key is fine, but API access is switched off for that user. In the Vultr portal go to Account, Users, edit the user, and click Enable API under User API Key. Until that switch is on, every call 403s no matter how valid the key is.

$ vultr-cli account get
{"error": "Forbidden", "status": 403}

Fix

1. Log into the Vultr customer portal as the account owner or an admin.
2. Go to Account, then Users under Other. Select the user and click the Edit User icon.

3. Click Enable API under User API Key. Save. Expected: the user's API status shows enabled.

4. Retry the CLI:

   vultr-cli account get

   Expected: account details print.

When this applies

• 403 Forbidden with a key that was just created and is correctly configured.
• The key belongs to a sub-user rather than the account owner.

When it does NOT apply

• 401 Invalid API key: the key itself is bad; regenerate it.
• 403 right after enabling IP allowlist changes: the runner's IP is blocked, different cause.

Compatibility

• vultr-cli against the Vultr API v2; portal user management.

Why it happens

Vultr gates API usage per user in addition to key validity. Sub-users are created API-disabled by default, so a freshly minted key for such a user authenticates (the key exists) but is refused at the authorization step.

Edge cases

• Only admins can flip the switch; if you are the sub-user, ask the account owner.
• Disabling and re-enabling can be used to quickly cut off a compromised sub-user key.
• The main account owner's key never hits this; if the owner 403s, look at IP allowlists instead.

The Vultr platform documentation 'How to Enable Vultr API Access for Users' (docs.vultr.com/public/doc-assets/pdfs/collectionitem/platform-other-users-manage-users-api-access.pdf) documents this exact gate: 'Application Programming Interface (API) access allows users to access the Vultr account programmatically' and gives the per-user enablement flow - 'Navigate to Account and select Users under OTHER. Select the user from the list and click the Edit User icon. Click Enable API under User API Key.' A sub-user with API disabled gets 403 even with a syntactically valid key, because the account-level switch is off. Source: https://docs.vultr.com/public/doc-assets/pdfs/collectionitem/platform-other-users-manage-users-api-access.pdf