CLI Configuration

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

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=

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.

    Loading...
  • BLACKFIRE_LOG_LEVEL

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

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

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

    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

    Defines which API endpoint the profile data is sent to.

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

    Enables or disables Blackfire Monitoring.

    1
    BLACKFIRE_APM_ENABLED=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):

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