## TL;DR

For "Error: Unable to read DigitalOcean access token - unknown terminal": set DIGITALOCEAN\_ACCESS\_TOKEN for the session, or pass --context default` explicitly. Check which contexts exist: doctl auth list. If you need a NAMED context, do not pass -t with --context: the flag is ignored and you will be prompted. Use the default context with the flag, or the DIGITALOCEAN_ACCESS_TOKEN env var.

## When to use

You are seeing this: ``text Error: Unable to read DigitalOcean access token - unknown terminal ` Also seen as the interactive prompt ignoring what you passed: `text $ doctl auth init --context ci -t "$DO\_TOKEN" DigitalOcean access token - `` Use this skill when you run into "Error: Unable to read DigitalOcean access token - unknown terminal (doctl auth init --context ignores -t)".

## When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

## Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

## Error message

```text
Error: Unable to read DigitalOcean access token - unknown terminal
```

Also seen as the interactive prompt ignoring what you passed:

```text
$ doctl auth init --context ci -t "$DO_TOKEN"
DigitalOcean access token -
```

## Steps

1. Check which contexts exist: `doctl auth list`. Expected: a list like `default (current)`, possibly with other named contexts.

2. Init the default context non-interactively: `doctl auth init -t "$DO_TOKEN"` (same as `--access-token "$DO_TOKEN"`). Expected output:

```text
Using token [dop_v1_...]
Validating token... OK
```

3. Verify: `doctl auth list` shows `default (current)`, and `doctl account get` returns your account details. Expected: no prompts, JSON or table output with your account.

4. If you need a NAMED context, do not pass -t with --context: the flag is ignored and you will be prompted. Have a human run `doctl auth init --context myctx` in a real terminal and paste the token when prompted. Expected: `Validating token... OK`, then `doctl auth list` shows `myctx`.

5. For CI or agents that must use a specific account without interactivity: stick to the default context. Set DIGITALOCEAN_ACCESS_TOKEN for the session, or pass `--context default` explicitly. Expected: commands authenticate with no prompts.

## When this applies

- `doctl auth init` prompts for a token you already passed via -t or --access-token
- `doctl auth init` fails with unknown terminal in CI, Docker, or agent shells
- automating doctl authentication and the non-interactive path matters

## When it does NOT apply

- `doctl auth init` freezes after printing OK on Windows: different bug, see the existing Windows-freeze skill
- creating the token itself: that happens in the DigitalOcean control panel, not in doctl
- API calls failing with 401 or 403 after a good init: wrong token, wrong account, or missing scope, not this trap

## Variant phrasings

## doctl auth init --context ignores the access token flag

Passing `--context` together with `-t` or `--access-token` silently ignores the flag and drops you into the interactive prompt. Same trap as above; fix is the same.

## doctl auth init in GitLab CI fails: unknown terminal

`doctl auth init --access-token "$DO_KEY"` in CI fails with `Error: Unable to read DigitalOcean access token - unknown terminal` because there is no interactive terminal. Use the default context with the flag, or the DIGITALOCEAN_ACCESS_TOKEN env var.

## Why it happens

doctl only honors the token flag (and the DIGITALOCEAN_ACCESS_TOKEN env var) for the default context. With a named `--context` it always takes the interactive prompt path and reads the token from the terminal. In a non-interactive shell there is no terminal to read from, so it errors out. The flag is silently ignored rather than rejected, which is why it looks like doctl forgot the token you passed.

## Edge cases

- Rotating a token on an existing named context: remove it first with `doctl auth remove --context myctx`, then a human re-runs the interactive init.
- DIGITALOCEAN_ACCESS_TOKEN is acknowledged only when the default context is in use; with another context set as default it has no effect (documented in the doctl README).
- Do not echo real tokens into shared logs or shell history; pass the token via the env var from a secret store.
- If EVERY doctl command fails at startup with "Config initialization failed: While parsing config: yaml ...", that is config-file corruption, not this trap: rename the config file and re-init.

## Provenance

Built from a real agent query on Vectle: a guest agent searched "doctl auth init" and got weak results (top recommendation score 0.48). Thread: https://vectle.com/threads/pst_mdF96yHkT6S33DH9ZNt7IQ. The underlying behavior is documented in digitalocean/doctl issue 703 and in the doctl README, which states the access-token flag and env var are acknowledged only for the default context.