CLI

The Bulkgrid CLI supports browser login, connection status, logout, MCP client configuration, and API-key source management. Use the API or SDK to submit crawl and extraction jobs; the CLI does not provide crawl or search subcommands.

Install

npm install -g @bulkgrid/cli
bulkgrid --help

You can also run commands without installing globally:

npx -y @bulkgrid/cli login

bulkgrid login

The browser opens the same workspace and collection consent page used by MCP clients. Sign in, review the selected workspace and collections, and approve access. Return to the terminal to confirm login completed. The connection appears as Bulkgrid CLI under Settings → Connected Apps. It receives mcp:use and search:query, with the collection restrictions you approved.

bulkgrid status
bulkgrid logout

status checks server access and refreshes expired tokens when needed. logout revokes this CLI connection and removes local tokens; other devices and your browser login remain separate.

Option	Purpose
`--url <base-url>`	Use another Bulkgrid deployment
`--no-browser`	Print the authorization URL without opening it

Use the same base URL for login, status, and logout, or set BULKGRID_URL. The default is https://bulkgrid.com.

bulkgrid login --url http://localhost:3000
bulkgrid status --url http://localhost:3000
bulkgrid logout --url http://localhost:3000

Remote deployments require HTTPS. Open the login link on the computer running the CLI so the local callback can complete. Login times out after five minutes; Ctrl+C cancels it.

Configure AI clients

init configures the MCP server for Cursor, VS Code, Claude Code, and Codex using API keys:

export BULKGRID_MCP_URL='https://bulkgrid.com/api/v1/mcp'
export BULKGRID_API_KEY='bg_live_your_api_key'
bulkgrid init --all

Use --cursor, --vscode, --claude, or --codex to configure one client. Keys need mcp:use and search:query for MCP search. CLI login and AI-client login are separate connections. init does not copy your CLI OAuth tokens into client configuration. For browser OAuth in an AI app, follow MCP setup.

Option	Purpose
`--mcp-url <url>`	Override `BULKGRID_MCP_URL`
`--global` / `--project`	Choose the configuration scope where supported
`--yes`	Disable interactive prompts; provide required values through flags or environment
`--auth browser`	Open the dashboard to create an API key
`--auth manual` / `--auth skip`	Paste a key or configure authentication later
`--write-api-key`	Store the supplied key in generated JSON config; avoid committing these files

Local credentials and recovery

Tokens are stored per deployment in ~/.config/bulkgrid with owner-only file permissions. The CLI refreshes tokens automatically and keeps them out of project configuration. If remote logout fails, credentials remain available for retry. If access was already revoked, or after revoking it in Connected Apps, clear the local credentials with:

bulkgrid logout --local

This option removes local tokens only. If a command reports a leftover authentication lock after a process stopped, ensure no authentication command is running before removing the specific lock file identified by the error.

Source management with an API key

The repository build includes sources commands. Check bulkgrid sources --help for availability in your installed release. These commands require BULKGRID_API_KEY; they do not use the saved OAuth login. Set BULKGRID_URL or pass --url to select another deployment. Remote deployments require HTTPS.

bulkgrid sources find https://example.com
bulkgrid sources collections

find requires sources:read; collections requires collections:read. For source-size inspection, explicitly start asynchronous analysis using sources analyze <url>, then check it with sources analysis-status <analysisId>. Analysis may consume resources; its URL counts and warnings are not a storage or credit quote. After choosing and authorizing the ingestion configuration:

bulkgrid sources add --input '{"type":"domain","identifier":"https://example.com","visibility":"private","source_mode":"discover","crawl_config":{"includePaths":["/docs"],"maxPages":100,"maxDepth":3},"crawl_interval":"weekly"}'

add requires sources:write and may initiate ongoing ingestion. Visibility and refresh policy matter; the example requests a private source with weekly refresh. Plan limits still apply.

Command	Purpose	Additional scopes
`sources analyze <url>`	Start deeper analysis; may create a crawl run	`sources:discover`, `runs:write`
`sources analysis-status <analysisId>`	Read analysis progress	`sources:discover`
`sources status <sourceId>`	Read crawl/indexing status and size	`sources:read`
`sources recrawl <sourceId>`	Request a manual refresh	`sources:write`, `runs:write`
`sources rules <collectionId>`	Inspect collection access	`collections:read`
`sources include <sourceId> <collectionId>`	Include the whole source in a collection	`collections:write`

Commands output JSON and do not poll automatically. Save source, analysis, and run IDs. Do not blindly retry a timed-out mutation: it may already have succeeded. Source creation and collection inclusion are separate operations, and source creation alone does not mean content is searchable.

Get started

Index

More

Access and operations

Install

Configure AI clients

Local credentials and recovery

Source management with an API key

​Install

​Sign in

​Login options

​Configure AI clients

​Local credentials and recovery

​Source management with an API key

Install

Sign in

Login options

Configure AI clients

Local credentials and recovery

Source management with an API key