Bright Data CLI FAQs

FAQs and troubleshooting for the Bright Data CLI: brightdata and bdata aliases, authentication, installation issues and common errors across 1000+ scrapers.

Frequently asked general questions

What is the difference between `brightdata` and `bdata`?

They are identical - bdata is a shorthand alias installed alongside brightdata. Use whichever you prefer.

Do I need a Bright Data account to use the CLI?

Yes. The CLI connects to Bright Data’s infrastructure to handle web requests. You can sign up for free and get started with the free tier.

What platforms can I extract data from?

The CLI supports 40+ platforms through the pipelines command, including Amazon, LinkedIn, Instagram, TikTok, YouTube, Facebook, Reddit, Google Maps, Walmart, eBay, and many more. Run brightdata pipelines list to see the full list.

What output formats are supported?

• Scrape: markdown (default), html, json, screenshot
• Search: Formatted table (default), json, pretty
• Pipelines: json (default), csv, ndjson, jsonl

All commands support -o <path> to write output to a file.

Can I use the CLI in scripts and CI/CD pipelines?

Yes. The CLI is fully pipe-friendly. When stdout is not a TTY, colors and spinners are automatically disabled. Use --json for machine-readable output and BRIGHTDATA_API_KEY environment variable for non-interactive authentication.

Authentication

Where are my credentials stored?

Credentials are stored locally on your machine:

OS	Path
macOS	~/Library/Application Support/brightdata-cli/credentials.json
Linux	~/.config/brightdata-cli/credentials.json
Windows	%APPDATA%\brightdata-cli\credentials.json

The file is set to mode 0o600 (owner read/write only).

How do I log in on a remote server without a browser?

Use the device flow:

brightdata login --device

This prints a URL and a verification code. Open the URL on any device with a browser, enter the code, and authentication completes on the server.

How do I switch between Bright Data accounts?

Run brightdata logout followed by brightdata login with the new account. Or pass a different API key directly:

brightdata login --api-key <new_key>

Troubleshooting

"No Web Unlocker zone specified"

This means no default zone is configured. Fix it by either:

# Re-run login (auto-creates zones)
brightdata login

# Or set a zone manually
brightdata config set default_zone_unlocker <zone_name>

"Invalid or expired API key"

Your stored API key is no longer valid. Re-authenticate:

brightdata login

"Access denied"

Your API key does not have permission for the requested zone or operation. Check zone permissions in the Bright Data control panel.

"Rate limit exceeded"

You’ve hit the rate limit for your zone. Options:

• Wait a moment and retry
• Use --async for large jobs to avoid blocking
• Contact your account manager to increase limits

Pipeline job timed out

The default polling timeout is 600 seconds (10 minutes). For large datasets, increase it:

# Per-command
brightdata pipelines amazon_product "<url>" --timeout 1200

# Via environment variable
export BRIGHTDATA_POLLING_TIMEOUT=1200

Colors or spinners look broken in my terminal

The CLI auto-detects TTY support. If detection fails, pipe through cat to force plain output:

brightdata scrape https://example.com | cat

Or use --json for clean, parseable output.

Frequently asked configuration questions

How do I change the default output format?

brightdata config set default_format json

Valid values: markdown, json.

What is the configuration priority order?

Settings are resolved in this order (highest priority first):

1. CLI flags - e.g., --zone my_zone
2. Environment variables - e.g., BRIGHTDATA_UNLOCKER_ZONE
3. config.json - e.g., default_zone_unlocker
4. Defaults - built-in fallbacks

How do I reset all configuration?

Delete the configuration directory:

# Linux
rm -rf ~/.config/brightdata-cli/

# macOS
rm -rf ~/Library/Application\ Support/brightdata-cli/

Then run brightdata login to start fresh.