# CLI Configuration

The Blackfire CLI can be configured via a configuration file, flags passed to the binary, or environment variables.

## Configuring the CLI via a Configuration File

The Blackfire CLI is configured by default with a `.blackfire.ini` file that can be found:

- in `$BLACKFIRE_HOME/.blackfire.ini` if you have defined the `$BLACKFIRE_HOME` environment variable;
- On Linux systems, in `$XDG_CONFIG_HOME/.blackfire.ini`;
- On all systems, in `$HOME/.blackfire.ini`;
- On Windows systems, in `$HOMEDRIVE/$HOMEPATH/.blackfire.ini`.

The most important entries are `client-id` and `client-token`. Here is a typical configuration for the CLI that you can use as a template:

```ini
[blackfire]
;
; setting: client-id
; desc   : Sets the Client ID used for API authentication
; default:
client-id=<YOUR_CLIENT_ID>

;
; setting: client-token
; desc   : Sets the Client Token used for API authentication
; default:
client-token=<YOUR_CLIENT_TOKEN>

;
; setting: http-proxy
; desc   : Sets the HTTP proxy to use
; default:
; http-proxy=

;
; setting: https-proxy
; desc   : Sets the HTTPS proxy to use
; default:
; https-proxy=

;
; setting: endpoint
; desc   : Sets the API endpoint
; default: https://blackfire.io
; endpoint=https://blackfire.io

;
; setting: timeout
; desc   : Sets the Blackfire API connection timeout
; default: 15s
; timeout=15s

;
; setting: ca-cert
; desc   : Sets the PEM encoded certificates to use
; default:
; ca-cert=
```

## Configuring the CLI via Environment Variables

The CLI can also be configured using environment variables:

- `BLACKFIRE_CLIENT_ID` / `BLACKFIRE_CLIENT_TOKEN`

    Sets the client ID and client Token used to authenticate with Blackfire.
- `BLACKFIRE_LOG_LEVEL`

    Sets the verbosity of the Probe's log output. Default value is `1` (error).

    ```bash
    # 1: error
    # 2: warning
    # 3: info
    # 4: debug
    BLACKFIRE_LOG_LEVEL=1
    ```
- `BLACKFIRE_LOG_FILE`

    Defines where the output of the probe logs is sent. Default value is empty.

    ```bash
    BLACKFIRE_LOG_FILE="/tmp/probe.log"
    ```
- `BLACKFIRE_AGENT_SOCKET`

    Defines which socket the Probe contacts the Agent on. Possible values can be a Unix socket or a TCP address.

    The default value is platform dependent, as detailed below.

    On Linux:

    ```bash
    BLACKFIRE_AGENT_SOCKET="unix:///var/run/blackfire/agent.sock"
    ```

    On macOS:

    ```bash
    # amd64
    BLACKFIRE_AGENT_SOCKET="unix:///usr/local/var/run/blackfire-agent.sock"
    
    # arm64 (M1)
    BLACKFIRE_AGENT_SOCKET="unix:///opt/homebrew/var/run/blackfire-agent.sock"
    ```

    On Windows:

    ```bash
    BLACKFIRE_AGENT_SOCKET="tcp://127.0.0.1:8307"
    ```
- `BLACKFIRE_ENDPOINT`

    Defines which API endpoint the profile data is sent to.

    ```bash
    BLACKFIRE_ENDPOINT="https://blackfire.io"
    ```
- `BLACKFIRE_APM_ENABLED`

    Enables or disables Blackfire Monitoring.

    ```bash
    BLACKFIRE_APM_ENABLED=1
    ```
- `BLACKFIRE_APM_ENABLE_AUTOMATIC_BROWSER_PROBE`

    Controls Front-end Observability tracking snippet injection.

    ```bash
    BLACKFIRE_APM_ENABLE_AUTOMATIC_BROWSER_PROBE=1
    ```

You can set these environment variables in the local `.env` file of your project if supported. Alternatively, you can set them in your global shell configuration file (such as `~/.bashrc` or `~/.zshrc`):

```bash
export BLACKFIRE_CLIENT_ID=xxx
export BLACKFIRE_CLIENT_TOKEN=yyy
export BLACKFIRE_LOG_LEVEL=4
export BLACKFIRE_LOG_FILE=/tmp/probe.log
```