feat: one token resolution order across every command

[l2ysho]

Note

TL;DR — Three resolvers decided which token a command used and they disagreed, and getLoggedClient() persisted whatever it resolved, so a one-off token overwrote the stored login. Now there is one order — APIFY_TOKEN → stored — only apify login writes credentials, and the CLI says out loud when the env var is in charge.

Stacked on #1417 (Stage-0). Base branch is claude/github-issue-1387-d39d52, not master.

What changed

1. refactor: stop credential reads from writing credentials — the write guard.

• New src/lib/auth.ts. resolveAuth() reads only; loginWithToken() authenticates and saves.
• apify login is the only caller of loginWithToken(). It now replaces the stored account instead of merging into it, so fields the new account lacks cannot linger from the old one.
• getLoggedClient() verifies the token and returns a client. It writes nothing, and is no longer exported — getLoggedClientOrThrow() is the only entry.
• The 15 call sites that read username/id to address API resources moved from getLocalUserInfo() to a new getCurrentUserInfo(). They relied on getLoggedClient() refreshing auth.json, which is the write that went away.

2. feat: one token resolution order across every command — precedence.

• APIFY_TOKEN → stored login, everywhere. This is the order mcp install and the actor entrypoint already used. APIFY_TOKEN is how you run a command as a different account.
• getApifyTokenFromEnvOrAuthFile (lib/actor.ts) and resolveApifyToken (mcp/install.ts) are gone. No special case for the actor entrypoint: inside a platform run there is no stored login, so APIFY_TOKEN wins on its own.
• apify auth token prints the token that would be used. It only looked right before because reads overwrote the stored token.
• apify info names the source, so an APIFY_TOKEN that overrides a stored login is visible.
• apify run passes the resolved token to the child and no longer overwrites an inherited APIFY_TOKEN.
• A rejected token names its source. A 401/403 says the token was rejected; anything else says the API request failed, so an unreachable API is not reported as a bad token.
• apify login ignores APIFY_TOKEN.
• useAuthSetup, credentials.test.ts and the e2e run-cli helper pin APIFY_TOKEN empty. Without that, a token in the developer's shell decides which account the tests run as.

3. feat: say when APIFY_TOKEN overrides a login or is ignored — the notices.

• A placeholder value falls back to the stored login, with Warning: APIFY_TOKEN is invalid: "undefined". APIFY_TOKEN=$UNSET_VAR leaves an empty string and templating an absent value writes the literal undefined. The value is trimmed.
• When APIFY_TOKEN overrides a stored login, Warning: Using the API token from APIFY_TOKEN. — once per command. Silent when the env var is the only credential, so CI and platform runs get no noise.
• apify login warns that APIFY_TOKEN keeps winning — otherwise its success message is a lie. apify logout warns that APIFY_TOKEN still authenticates.
• All notices go to stderr, so auth token stays pipeable and --json stays parseable.
• A token the API rejects with 401/403 does not fall back. APIFY_TOKEN=$CUSTOMER apify push with an expired customer token would otherwise push into your own account — the silent wrong-account write this branch removes.

Closes #1418. Closes #720.

Deviation from the issue: no global --token

Issue #1418 scoped --token as a global flag in baseOptions. I built that, then dropped it.

--token stays where it already was, on login and mcp install — the two commands that write the token somewhere rather than just authenticating with it. Everywhere else, APIFY_TOKEN already does the job, so a global flag would be a second mechanism for one thing. It also parsed on ~40 commands that never authenticate, where apify auth logout --token X reads as "log out that token", and it added 445 lines to docs/reference.md documenting a no-op. The resolver still takes an explicit token, so re-adding the flag later is a one-line registration.

Worth noting for anyone on Windows: APIFY_TOKEN=x apify call ... needs $env:APIFY_TOKEN in PowerShell or set in cmd. If that turns out to be a real complaint, the flag comes back.

The issue body should be updated to match.

Behavior, before and after

Run against two real accounts, account-a (logged in) and account-b ($B), with 1.10.0 side by side.

APIFY_TOKEN no longer ignored

Command	Before	Now
APIFY_TOKEN=$B apify actors ls	lists account-a's Actors	lists account-b's Actors
APIFY_TOKEN=$B apify actors ls (logged out)	Error: You are not logged in	lists account-b's Actors
APIFY_TOKEN=$B apify info	username: account-a	username: account-b + token source: APIFY_TOKEN environment variable
APIFY_TOKEN=$B apify auth token	prints account-a's token	prints account-b's token
APIFY_TOKEN=$B apify actors info <name>	resolves account-a/<name> → not found	resolves account-b/<name> → found

The env var was ignored even when it was the only credential available.

apify run handed the child the wrong identity

Command	Before	Now
APIFY_TOKEN=$B apify run	child gets account-a's token, user id and proxy password	child gets account-b's

localEnvVars overwrote the inherited APIFY_TOKEN. This is the "Insufficient permissions for the Actor run" report, and why it started working after apify logout.

Reads overwrote the stored login

Command	Before	Now
APIFY_TOKEN=$B apify actor charge result-item	errors on the missing run id — and auth.json now holds account-b. Unsetting APIFY_TOKEN does not restore account-a	same error, auth.json untouched

The write landed before the run-id check, so it reproduced outside a real Actor run.

Junk values and dead tokens

Command	Before	Now
APIFY_TOKEN=undefined apify actors ls	silently uses stored login	Warning: APIFY_TOKEN is invalid: "undefined". then uses stored login
APIFY_TOKEN= apify actors ls	silently uses stored login	unchanged — an unset variable is not worth a message
APIFY_TOKEN=" $B " apify actors ls	uses stored login	trimmed, uses account-b
APIFY_TOKEN=<revoked> apify actors ls	silently succeeds as account-a	Error: The API token in APIFY_TOKEN was rejected. Unset it to use your stored login instead.

Silence that misled

Command	Before	Now
APIFY_TOKEN=$B apify login --token $A	Success: logged in as account-a — while every later command ran as account-b	same line + Warning: APIFY_TOKEN is set, so other commands keep using that token instead of this login.
APIFY_TOKEN=$B apify logout	Success: logged out — while commands stayed authenticated	same line + Warning: APIFY_TOKEN is still set, so commands stay authenticated with that token.
apify login --token <bad>	exit 0 — apify login --token $BAD && apify push ran on	exit 1

Verification

• pnpm run test:local — 616 passed, 4 skipped (62 files).
• APIFY_TOKEN=<bogus> pnpm run test:local — 616 passed, 4 skipped. Catches tests that fall through to the real API.
• pnpm run lint, pnpm run format, pnpm run build — clean.
• pnpm run update-docs — docs/reference.md regenerated and committed (11 lines: three description changes).
• pnpm run test:api not run — no token in this environment.
• 31 new tests: resolver precedence, the write guard on every read path, the four auth-failure messages, placeholder fallback, and every notice.

Requires Node ≥22 to run pnpm 11 locally.

Upgrade note

A stale APIFY_TOKEN in a shell profile or CI job now decides which account commands run as, where the CLI used to quietly ignore it. A junk value falls back with a message; a real but revoked token fails with one. Worth a release note.

Left out, deliberately

• auth.json metadata is no longer refreshed every run. On the stored-login path, a user who renames their account or switches org has to re-login to get correct console URLs and name lookups. Cosmetic, and it is the point of the write guard.
• Exit codes are fixed on the auth paths only. The rest of the CLI stays with Many commands exit with code 0 on failure (and some failures skip telemetry) #1254.
• feat(auth): treat APIFY_TOKEN env var as authenticated in non-interactive contexts #1246 (the earlier env-first draft, no write guard) still needs closing by hand.
• Install size unchanged — no dependency added or removed.

🤖 Generated with Claude Code