Skip to content

fix(auth): point unauthenticated errors at browser login - #384

Merged
Ben2W merged 1 commit into
mainfrom
fix/unauthenticated-login-guidance
Nov 11, 2026
Merged

Ben2W merged 1 commit into
mainfrom
fix/unauthenticated-login-guidance

Conversation

@Ben2W

@Ben2W Ben2W commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

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

Without a terminal, commands that need an account told the caller to set
an API key or run "firecrawl login" in a terminal. An agent has no
terminal, but "firecrawl login --browser" asks nothing on stdin, so it
could have signed in all along.

Every unauthenticated path now shares one message that leads with
"firecrawl login --browser" and keeps FIRECRAWL_API_KEY and --api-key as
the alternatives. The --status and setup hints name the same command,
and the install skill describes what an agent actually sees.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

@KrisOei KrisOei left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice

@Ben2W
Ben2W merged commit a2f9033 into main Nov 11, 2026
8 checks passed
@Ben2W
Ben2W deleted the fix/unauthenticated-login-guidance branch November 11, 2026 21:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants