--- title: CLI Quickstart --- # CLI Quickstart ## Pre-requisites In order to be able to use the CLI, you need to have a bitdrift account. !!! note "" Sign up for a [free trial](https://bitdrift.io/signup), or talk to your bitdrift administrator about getting started. ## Installation The CLI is currently only supported on macOS and can be installed via Homebrew: ```sh brew tap bitdriftlabs/bd brew install bd ``` ### Update Notices

Interactive human-output commands check for newer stable CLI releases using a small public manifest at `https://dl.bitdrift.io/bd-cli/latest/version.json`. When an update is available, a notice on stderr includes the release download link. The CLI does not install updates automatically. For a Homebrew installation, upgrade with: ```sh brew update && brew upgrade bitdriftlabs/bd/bd ``` The Homebrew formula may become available after the release download. Successful checks are cached for one day. When a newer release is available, a notice is shown on every eligible invocation, including when the version information comes from the cache. A due check waits up to one second before the command starts. An unfinished refresh continues silently while the command runs, with a ten-second total network deadline, and caches its result for the next invocation. It stops when the CLI process exits. Offline and failed checks do not interrupt commands. Failed checks are retried after one hour; cached metadata remains usable for up to seven days. Update state is stored in `~/.bd/update-check.json`, separately from your configuration and credentials. Checks are skipped for machine-readable output, redirected streams, CI, MCP, connectivity diagnostics, and local-only utilities. Set `BD_DISABLE_UPDATE_CHECK=1` to disable checks and notices entirely. ## Usage ### Authentication The CLI relies on authenticating the user with the bitdrift SaaS to enforce access control. To authenticate, invoke ```sh bd auth ``` This will open up a browser-based login flow where the user may log in via their preferred mechanism. For day-to-day interactive use, `bd auth` is the simplest option. The CLI also supports API-key based authentication for scripting and automation via `--api-key ` or the `BD_API_KEY` environment variable. ### Public API command groups In addition to `auth` and `tail`, the CLI now exposes several command groups backed by bitdrift's public APIs. These commands are useful when you want to automate common workflows, inspect resources from a terminal, or integrate bitdrift into shell scripts and CI jobs. Most of these commands support both human-readable output and `-o json` for scripting. For non-interactive usage, prefer an API key instead of a browser login. Use `bd --help` to see the current top-level command surface, then drill into a specific area with `bd --help` such as `bd workflow --help` or `bd issue group --help`. The CLI help output is the fastest way to discover newly added subcommands and flags. | Command group | Use it for | Common starting point | | --- | --- | --- | | `bd key` | Creating, listing, and revoking access keys | `bd key list` | | `bd issue` | Navigating issue groups, issues, and captured feature-flag state | `bd issue group list` | | `bd connector` | Managing outbound data connectors | `bd connector list` | | `bd slack` | Authorizing Slack connections and selecting granted workspaces | `bd slack connect` | | `bd workflow` | Inspecting, creating, updating, deploying, and stopping workflows | `bd workflow list` | | `bd charts` | Loading chart data or hydrating deferred chart dimensions | `bd charts load --request-file chart-request.json` | | `bd timeline` | Hydrating a session timeline and fetching session logs | `bd timeline hydrate ` | #### Choosing an authentication mode Use `bd auth` when you are exploring interactively as yourself. Prefer an API key for repeatable automation or running the CLI in CI. Direct public API calls outside the CLI support either an API key or a user session JWT; see [Calling the API](../api-guide/calling-the-api.md#authentication) for the request headers and token-lifecycle considerations. The CLI can also help you bootstrap that workflow: - `bd key create api` creates an API key with explicit permissions for public API access. - Symbol-upload automation requires the `debug-file-upload` permission. See [Uploading Debug Information Files](../sdk/features/fatal-issues.md#uploading-debug-information-files). For lower-level API usage, request payloads, or transport-specific examples, see [Calling the API](../api-guide/calling-the-api.md). ### Enterprise Slack

Use `bd slack connect` to start authorization for the current bitdrift tenant. For an Enterprise Grid organization installation, a Slack organization admin must authorize the organization and grant workspace access. Then use `bd slack workspaces list`, `bd slack workspace select `, and `bd slack status` to finish setup. See the [Enterprise Slack integration guide](../product/admin/integrations.md#enterprise-slack) for permissions, the complete authorization flow, connection states, and disconnect behavior. #### Create or update workflow chart metadata `bd workflow create` and `bd workflow update` accept workflow chart metadata as protobuf JSON. Keep the workflow definition and chart metadata in separate files, then pass the metadata with `--chart-metadata-file`: ```sh bd workflow create workflow.json \ --chart-metadata-file chart-metadata.json \ --platform android \ --deploy bd workflow update \ --workflow-id \ --chart-metadata-file chart-metadata.json ``` The following example selects the three new metric display modes. The `ruleId` must match the metric chart rule in `workflow.json`. ```json [ { "ruleId": "requests_by_endpoint", "metadata": { "metricChartMetadata": { "basicBarChartDisplayMode": {} } } }, { "ruleId": "requests_by_status", "metadata": { "metricChartMetadata": { "pieChartDisplayMode": {} } } }, { "ruleId": "request_volume_by_endpoint", "metadata": { "metricChartMetadata": { "heatMapDisplayMode": { "counterCalculation": { "aggregationType": "SUM" }, "counterSizing": "COUNTER_SIZING_UNIQUE_DEVICES", "colorThresholds": { "values": [10, 50, 100, 250] } } } } } ] ``` `counterSizing: COUNTER_SIZING_UNIQUE_DEVICES` requires the workflow time series to track unique device IDs. Use `bd charts load --request-file --output json` to retrieve chart data. If the response includes deferred dimensions, pass the corresponding hydrate request to `bd charts hydrate --request-file --output json` to retrieve unique-device counts. ### Log Tailing To tail logs from devices connected to the bitdrift SaaS, use the `bd tail` command. This accepts a query expression that is used to specify both the devices to target as well as specifying what logs are of interest. #### Log Tailing Query Expression The query expression makes use of a series of _operators_ which may accept a variable number of _operator arguments_. For example, the expression ```sh bd tail apple field foo bar normal level debug ``` Would be parsed as `(apple) (field foo bar) (level debug)` and contain three operators: - `apple` - target all Apple (iOS) devices - `field` with the arguments `foo` and `bar` - only tail logs with field `foo` equal to `bar` - `level` with the argument `debug` - only tail logs at `debug` level A complete list of operators can be found below: - `apple` - target all Apple (iOS) devices - `android` - target all Android devices - `appversion ` - target all devices with the specific app version - `deviceid ` - target the device with the specific bd device id [device code](../sdk/features/device.md#identifier) - `devicecode

` / `code ` - target the device with the specific generated [device code](../sdk/features/device.md#code)
- `appid ` - target all devices with the specific app id
- `level ` / `loglevel ` - tail logs with the specificed log level
- `field  ` / `f  ` - tail logs with field `` = ``

#### Log Formatting

When using the default output, logs are rendered with the log metadata and the log message. To
modify the message rendered for each log, a [VRL](https://vector.dev/docs/reference/vrl/) program
can be provided which can be used to modify the displayed text as well as drop unnnecessary logs.

Within the configuration file located at `~/.bd/config.yaml` or specified via the `--config` flag, specify
the VRL program under the `vrl_program` key. For example:

```yaml
vrl_program: |
  if .msg == "don't need this" {
    abort
  }

  if .field.foo == "foo_value" {
    msg = .msg
    bar_value = .field.bar

    . = "{{ msg }} {{ bar_value }}"
  }
```

Will drop all logs with the log message `don't need this` and will rewrite the displayed message for all logs
with a field `foo=foo_value` to instead read ` `.

The schema to keep in mind for the VRL programs:

- `.msg` holds the log message
- `.field.` holds the value of field `key` or nil if not present
- `.` used to specify how this log line should be rendered

### Log Types

Each log is annotated with a log type that helps explain what kind of a log it is. Within the default `bd tail` output, this is rendered as
the second column.

The possible values for the log type is

- `netw`: Network logs emitted by various library integrations within the Capture SDK or via logNetworkRequest / logNetworkResponse.
- `resr`: Resource logs emitted by the periodic resource monitors within the Capture SDK.
- `repl`: Session replay logs emitted by the Capture SDK.
- `cstm`: Custom logs fed into the Capture SDK via `Logger.log` methods.
- `othr`: Other unclassified logs.