Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion skills/firecrawl/rules/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 "<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

Expand Down
4 changes: 3 additions & 1 deletion src/__tests__/utils/auth.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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!')
Expand Down
4 changes: 3 additions & 1 deletion src/__tests__/utils/config.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand Down
4 changes: 2 additions & 2 deletions src/commands/alexandria.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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}`
);
}

Expand Down
4 changes: 2 additions & 2 deletions src/commands/doctor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -679,7 +679,7 @@ export async function runSupportAsk(options: DoctorOptions): Promise<number> {

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;
}
Expand Down
2 changes: 1 addition & 1 deletion src/commands/setup.ts
Original file line number Diff line number Diff line change
Expand Up @@ -444,7 +444,7 @@ async function offerSkillsAuth(options: SetupOptions): Promise<void> {

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;
}
Expand Down
4 changes: 3 additions & 1 deletion src/commands/status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -268,7 +268,9 @@ export async function handleStatusCommand(): Promise<void> {
);
} 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(
Expand Down
5 changes: 2 additions & 3 deletions src/commands/terms.ts
Original file line number Diff line number Diff line change
@@ -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';

Expand Down Expand Up @@ -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 ||
Expand Down
6 changes: 2 additions & 4 deletions src/utils/auth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand Down Expand Up @@ -813,9 +813,7 @@ export async function ensureAuthenticated(): Promise<string> {

// 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);
}

Expand Down
12 changes: 9 additions & 3 deletions src/utils/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand All @@ -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}`);
}
}

Expand Down
Loading