fix(auth): point unauthenticated errors at browser login

Merged
BE
8d ago
+28-19

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, doctor run diagnostics and requireAlexandriaKey all use it.
  • The --status hint and the non-interactive setup hint now name firecrawl login --browser instead of plain firecrawl login.
  • skills/firecrawl/rules/install.md said 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, list and --status with no credentials and stdin closed; each shows the new guidance.
  • Ran firecrawl login --browser with 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