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

## 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 <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 <command> --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 workflow` | Inspecting, creating, updating, deploying, and stopping workflows | `bd workflow list` |
| `bd timeline` | Hydrating a session timeline and fetching session logs | `bd timeline hydrate <session-id>` |

#### Choosing an authentication mode

Use `bd auth` when you are exploring interactively as yourself. Use an API key when you need
repeatable automation, want to run the CLI in CI, or need to call the public API directly outside of
the CLI.

The CLI can also help you bootstrap that workflow:

- `bd key create api` creates an API key with explicit permissions for public API access.

For lower-level API usage, request payloads, or transport-specific examples, see
[Calling the API](../api-guide/calling-the-api.md).

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

<script async id="asciicast-faHSKwgFoeogRvBuzIf0TwmdX" src="https://asciinema.org/a/faHSKwgFoeogRvBuzIf0TwmdX.js"></script>

#### 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 <version>` - target all devices with the specific app version
- `deviceid <id>` - target the device with the specific bd device id [device code](../sdk/features/device.md#identifier)
- `devicecode <code>` / `code <code>` - target the device with the specific generated [device code](../sdk/features/device.md#code)
- `appid <app id>` - target all devices with the specific app id
- `level <level>` / `loglevel <type>` - tail logs with the specificed log level
- `field <key> <value>` / `f <key> <value>` - tail logs with field `<key>` = `<value>`

#### 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 `<message> <value of field bar>`.

The schema to keep in mind for the VRL programs:

- `.msg` holds the log message
- `.field.<key>` 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.