fix(auth): point unauthenticated errors at browser login
Problem
When a command that needs an account runs with no credentials and no terminal (the situation every agent is in), the CLI said:
Error: Not authenticated. Set FIRECRAWL_API_KEY, pass --api-key, or run "firecrawl login" in a terminal.
That steers agents to an API key and tells them login needs a terminal. It does not: firecrawl login --browser asks nothing on stdin. It prints a sign-in URL and polls until the user approves it, so an agent can run it directly. Plain firecrawl login, which the old hints named, is the one that fails without a terminal.
Other unauthenticated paths were worse. validateConfig said "API key is required…" and pointed at firecrawl config, terms and doctor said to run plain firecrawl login, and the Alexandria commands gave no next step at all.
Change
One shared message, LOGIN_GUIDANCE in src/utils/config.ts, used by every unauthenticated path:
Error: Not authenticated. Run "firecrawl login --browser" to sign in: it needs no terminal input, prints a sign-in URL for the user to open, and waits up to 5 minutes for approval. Or set FIRECRAWL_API_KEY, or pass --api-key.
ensureAuthenticated(no-terminal branch),validateConfig,terms,doctorrun diagnostics andrequireAlexandriaKeyall use it.- The
--statushint and the non-interactivesetuphint now namefirecrawl login --browserinstead of plainfirecrawl login. skills/firecrawl/rules/install.mdsaid account-only commands "prompt an interactive login"; it now describes what an agent sees and what to do with the sign-in URL.
Interactive terminal behaviour is unchanged: the login prompt still appears there.
Testing
- Rebuilt and ran
crawl,credit-usage,monitor list,listand--statuswith no credentials and stdin closed; each shows the new guidance. - Ran
firecrawl login --browserwith stdin closed to confirm it prints the URL and polls without prompting. vitest run: 925 passed, 51 skipped. The two tests that pinned the old wording now assert the browser-login guidance.
🤖 Generated with Claude Code