1. Documentation
  2. Getting Up and Running
  3. Configuration
  4. CLI Configuration

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
[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

    Sets the client ID from the Client ID/Client Token credentials pair.

    or to display your Blackfire's credentials.

  • BLACKFIRE_CLIENT_TOKEN

    Sets the client Token from the Client ID/Client Token credentials pair.

    or to display your Blackfire's credentials.

  • BLACKFIRE_LOG_LEVEL

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

    1
2
    # 1: error, 2: warning, 3: info, 4: debug
BLACKFIRE_LOG_LEVEL=1

  • BLACKFIRE_LOG_FILE

    Sets the output destination of Probe’s log. Default value is empty.

    1
    BLACKFIRE_LOG_FILE="/tmp/probe.log"

  • BLACKFIRE_AGENT_SOCKET

    Sets the socket the Probe will contact 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:

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

    On macOS:

    1
2
3
4
5
    # 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:

    1
    BLACKFIRE_AGENT_SOCKET="tcp://127.0.0.1:8307"

  • BLACKFIRE_ENDPOINT

    Sets the API endpoint the profile data will be sent to.

    1
    BLACKFIRE_ENDPOINT="https://blackfire.io"

You can set these environment variables in a project’s local .env file if supported, or in your global shell configuration file (such as ~/.bashrc or ~/.zshrc):

1
2
3
4
export BLACKFIRE_CLIENT_ID=xxx
export BLACKFIRE_CLIENT_TOKEN=yyy
export BLACKFIRE_LOG_LEVEL=4
export BLACKFIRE_LOG_FILE=/tmp/probe.log