diff --git a/skills/firecrawl/rules/install.md b/skills/firecrawl/rules/install.md index 3a90def4cb..cfd17e3494 100644 --- a/skills/firecrawl/rules/install.md +++ b/skills/firecrawl/rules/install.md @@ -81,7 +81,7 @@ Ask the user how they'd like to authenticate: 1. **Login with browser (Recommended)** - Run `firecrawl login --browser` 2. **Enter API key manually** - Run `firecrawl login --api-key ""` with a key from firecrawl.dev -If you cannot obtain a key and the user cannot sign up, search, scrape, and interact still work without an API key on the keyless free tier (rate-limited). Commands that need an account — `crawl`, `map`, `download`, `agent`, `monitor`, `credit-usage`, and the feedback commands — prompt an interactive login when no credentials are set. Browser login or an API key remains preferred for the best results. See [agent onboarding](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for the full set of onboarding paths. +If you cannot obtain a key and the user cannot sign up, search, scrape, and interact still work without an API key on the keyless free tier (rate-limited). Commands that need an account — `crawl`, `map`, `download`, `agent`, `monitor`, `credit-usage`, and the feedback commands — prompt an interactive login in a terminal when no credentials are set; without one (an agent shell) they exit with `Not authenticated` and point at `firecrawl login --browser`, which needs no terminal input: run it, give the user the sign-in URL it prints, and it finishes once they approve. Browser login or an API key remains preferred for the best results. See [agent onboarding](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for the full set of onboarding paths. ### Command not found diff --git a/src/__tests__/utils/auth.test.ts b/src/__tests__/utils/auth.test.ts index c3326d1531..b91ac67a12 100644 --- a/src/__tests__/utils/auth.test.ts +++ b/src/__tests__/utils/auth.test.ts @@ -143,7 +143,9 @@ describe('Authentication Utilities', () => { await expect(ensureAuthenticated()).rejects.toThrow('process.exit(1)'); expect(console.error).toHaveBeenCalledWith( - expect.stringContaining('Not authenticated') + expect.stringContaining( + 'Not authenticated. Run "firecrawl login --browser"' + ) ); expect(console.log).not.toHaveBeenCalledWith( expect.stringContaining('Welcome!') diff --git a/src/__tests__/utils/config.test.ts b/src/__tests__/utils/config.test.ts index 6d2e83d4c2..2d460eeb53 100644 --- a/src/__tests__/utils/config.test.ts +++ b/src/__tests__/utils/config.test.ts @@ -265,7 +265,9 @@ describe('Config Fallback Priority', () => { it('should require API key for cloud API URL', () => { initializeConfig({ apiUrl: 'https://api.firecrawl.dev' }); - expect(() => validateConfig()).toThrow('API key is required'); + expect(() => validateConfig()).toThrow( + /Not authenticated\. Run "firecrawl login --browser"/ + ); }); it('should not throw when API key is provided for cloud API', () => { diff --git a/src/commands/alexandria.ts b/src/commands/alexandria.ts index 55f8ff74a1..9f05338b74 100644 --- a/src/commands/alexandria.ts +++ b/src/commands/alexandria.ts @@ -4,7 +4,7 @@ import { randomUUID } from 'node:crypto'; import { Command, Option } from 'commander'; import { type AlexandriaCall } from 'firecrawl'; import { getClient } from '../utils/client'; -import { getApiKey } from '../utils/config'; +import { getApiKey, LOGIN_GUIDANCE } from '../utils/config'; import { writeOutput } from '../utils/output'; import { withoutResultPrices } from '../utils/alexandria-prices'; import { @@ -29,7 +29,7 @@ export type AlexandriaOptions = { export function requireAlexandriaKey(apiKey?: string): void { if (!getApiKey(apiKey)) throw new Error( - 'Alexandria requires a Firecrawl API key with access enabled.' + `Not authenticated. Alexandria requires a Firecrawl account with access enabled. ${LOGIN_GUIDANCE}` ); } diff --git a/src/commands/doctor.ts b/src/commands/doctor.ts index 62d11849ec..268fe2a8d9 100644 --- a/src/commands/doctor.ts +++ b/src/commands/doctor.ts @@ -12,7 +12,7 @@ import { promises as fs } from 'fs'; import path from 'path'; import packageJson from '../../package.json'; -import { getConfig } from '../utils/config'; +import { getConfig, LOGIN_GUIDANCE } from '../utils/config'; import { isJobId } from '../utils/job'; import { detectAgents, type AgentDetection } from '../utils/agents'; import { compareVersions, getLatestVersion } from '../utils/npm-registry'; @@ -679,7 +679,7 @@ export async function runSupportAsk(options: DoctorOptions): Promise { if (!apiKey) { console.error( - `${red}Error:${reset} API key required for run diagnostics. Run \`firecrawl login\`.` + `${red}Error:${reset} Not authenticated. Run diagnostics need an account. ${LOGIN_GUIDANCE}` ); return 1; } diff --git a/src/commands/setup.ts b/src/commands/setup.ts index c159f9cad9..c9869350b2 100644 --- a/src/commands/setup.ts +++ b/src/commands/setup.ts @@ -444,7 +444,7 @@ async function offerSkillsAuth(options: SetupOptions): Promise { if (!login) { console.log( - `${dim}No Firecrawl API key found. Skills walk agents through setup on first use; to be ready now, run "firecrawl login" or export FIRECRAWL_API_KEY.${reset}` + `${dim}No Firecrawl API key found. Skills walk agents through setup on first use; to be ready now, run "firecrawl login --browser" or export FIRECRAWL_API_KEY.${reset}` ); return; } diff --git a/src/commands/status.ts b/src/commands/status.ts index de437284bb..deec122dc9 100644 --- a/src/commands/status.ts +++ b/src/commands/status.ts @@ -268,7 +268,9 @@ export async function handleStatusCommand(): Promise { ); } else { console.log(` ${red}●${reset} Not authenticated`); - console.log(` ${dim}Run 'firecrawl login' to authenticate${reset}`); + console.log( + ` ${dim}Run 'firecrawl login --browser' to authenticate${reset}` + ); console.log(''); if (localStatus.firecrawlDirExists) { console.log( diff --git a/src/commands/terms.ts b/src/commands/terms.ts index 52dd0f97e8..693f58ba22 100644 --- a/src/commands/terms.ts +++ b/src/commands/terms.ts @@ -1,5 +1,5 @@ import { Command } from 'commander'; -import { getApiKey, getConfig } from '../utils/config'; +import { getApiKey, getConfig, LOGIN_GUIDANCE } from '../utils/config'; import { writeOutput } from '../utils/output'; import { integrationHeaders } from '../utils/integration'; @@ -31,8 +31,7 @@ export async function requestTerms( if (!provider.trim() || provider.length > 200) throw new Error('Provide a provider ID of 1-200 characters.'); const key = getApiKey(options.apiKey); - if (!key) - throw new Error('A Firecrawl API key is required. Run firecrawl login.'); + if (!key) throw new Error(`Not authenticated. ${LOGIN_GUIDANCE}`); const base = ( options.apiUrl || getConfig().apiUrl || diff --git a/src/utils/auth.ts b/src/utils/auth.ts index cccf5693d7..75dc7da181 100644 --- a/src/utils/auth.ts +++ b/src/utils/auth.ts @@ -9,7 +9,7 @@ import { saveCredentials, getConfigDirectoryPath, } from './credentials'; -import { updateConfig, getApiKey } from './config'; +import { updateConfig, getApiKey, LOGIN_GUIDANCE } from './config'; import { promptInput } from './prompt'; import { bold, dim, orange, reset } from './terminal'; @@ -813,9 +813,7 @@ export async function ensureAuthenticated(): Promise { // Without a terminal the login prompt can never be answered. if (!process.stdin.isTTY) { - console.error( - 'Error: Not authenticated. Set FIRECRAWL_API_KEY, pass --api-key, or run "firecrawl login" in a terminal.' - ); + console.error(`Error: Not authenticated. ${LOGIN_GUIDANCE}`); process.exit(1); } diff --git a/src/utils/config.ts b/src/utils/config.ts index 1374a308fc..7b3af3d101 100644 --- a/src/utils/config.ts +++ b/src/utils/config.ts @@ -74,6 +74,14 @@ export function getApiKey(providedKey?: string): string | undefined { const DEFAULT_API_URL = 'https://api.firecrawl.dev'; +/** + * What to do when a command needs an account and none is configured. Browser + * login leads because it asks nothing on stdin, so an agent or script can run + * it; the person only has to open the printed URL. + */ +export const LOGIN_GUIDANCE = + '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.'; + /** * Check if using a custom (non-cloud) API URL */ @@ -94,9 +102,7 @@ export function validateConfig(apiKey?: string): void { const key = getApiKey(apiKey); if (!key) { - throw new Error( - 'API key is required. Set FIRECRAWL_API_KEY environment variable, use --api-key flag, or run "firecrawl config" to set the API key.' - ); + throw new Error(`Not authenticated. ${LOGIN_GUIDANCE}`); } }