> ## Documentation Index
> Fetch the complete documentation index at: https://bulkgrid.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install the Bulkgrid CLI, sign in, and configure AI clients.

The Bulkgrid CLI supports browser login, connection status, logout, MCP client configuration, and API-key source management. Use the [API](/docs/first-crawl-request) or [SDK](/docs/sdk) to submit crawl and extraction jobs; the CLI does not provide crawl or search subcommands.

## Install

```bash theme={null}
npm install -g @bulkgrid/cli
bulkgrid --help
```

You can also run commands without installing globally:

```bash theme={null}
npx -y @bulkgrid/cli login
```

## Sign in

```bash theme={null}
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.

```bash theme={null}
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.

## Login options

| 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`.

```bash theme={null}
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:

```bash theme={null}
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](/docs/mcp-server).

| 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:

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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.