id       = "blackfire"
name     = "Blackfire"
homepage = "https://www.blackfire.io"
description = "The only tool to offer natively integrated monitoring, advanced determinist and continuous profiling and testing features."
# The flame, from the site's own icon set.
icon     = "https://www.blackfire.io/icons/icon-512x512.png"
executables   = ["blackfire"]

[dotfiles]

# https://docs.blackfire.io/up-and-running/configuration/cli ("CLI
# Configuration"): "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 home-directory spelling is the one every platform shares, and the
# Windows one resolves to the same file. The Linux $XDG_CONFIG_HOME variant is
# a dotfile placed inside the XDG directory rather than a base-directory
# location, and no root here names it without also naming directories the CLI
# does not read on macOS and Windows, so it is left out.
paths = ["~/.blackfire.ini"]

exclude = []

# Not a credential end to end: the same file carries http-proxy, endpoint,
# timeout and ca-cert. Only the two authentication entries are lifted out.
secret = []

# Read when the command starts; `blackfire config` writes it back.
side_effect = false

# "The most important entries are client-id and client-token" — the pair used
# for API authentication (same page). The file is INI, so each is written as
# `<name>=<value>` on its own line.
[[dotfiles.secret_paths]]
file  = "~/.blackfire.ini"
match = { prefix = ["client-id", "client-token"] }

[commands]
format = 1
label = "Blackfire"
description = "Profile a command or an HTTP request with the Blackfire CLI. Authentication comes from ~/.blackfire.ini or BLACKFIRE_CLIENT_ID/BLACKFIRE_CLIENT_TOKEN; other subcommands are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.subcommand]]
path = ["run"]
label = "Profile a CLI command"
description = "Everything after the command is passed to the profiled program unchanged."

[[commands.subcommand.source]]
id = "cookbook"
kind = "manual"
url = "https://docs.blackfire.io/profiling-cookbooks/profiling-cli.md"
revision = "2026-10-27"
evidence = """
$ blackfire run php my-script.php
$ blackfire run php my-script.php --your-script-options and arguments
use the `--env=<ENV_UUID>` parameter.
use `--env="My Environment"`
$ blackfire --json run php my-script.php
$ blackfire --env <env-uuid> run php my-script.php
"""

[[commands.subcommand.field]]
id = "env"
label = "Environment"
description = "Environment UUID or name that receives the profile."
type = "string"
option = ["--env"]
value_style = "equals"
sources = ["cookbook"]

[[commands.subcommand.field]]
id = "json"
label = "JSON output"
type = "boolean"
option = ["--json"]
sources = ["cookbook"]

[[commands.subcommand.field]]
id = "program"
label = "Program and arguments"
description = "For example php my-script.php."
type = "string"
position = 0
multiple = true
sources = ["cookbook"]

[[commands.subcommand.task]]
id = "profile"
label = "Profile a script"
fields = ["env", "json", "program"]
required = ["program"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["program", "env", "json"]

[[commands.subcommand]]
path = ["curl"]
label = "Profile an HTTP request"
description = "Runs curl with Blackfire headers; other curl options are accepted by the tool but not modelled here."

[[commands.subcommand.source]]
id = "cookbook"
kind = "manual"
url = "https://docs.blackfire.io/profiling-cookbooks/profiling-http-via-cli.md"
revision = "2026-10-27"
evidence = """
blackfire curl http://example.com/
use the `--env=<ENV_UUID>` parameter.
use `--env="My Environment"`
blackfire --json curl http://example.com/
"""

[[commands.subcommand.field]]
id = "env"
label = "Environment"
type = "string"
option = ["--env"]
value_style = "equals"
sources = ["cookbook"]

[[commands.subcommand.field]]
id = "json"
label = "JSON output"
type = "boolean"
option = ["--json"]
sources = ["cookbook"]

[[commands.subcommand.field]]
id = "url"
label = "URL"
type = "url"
position = 0
sources = ["cookbook"]

[[commands.subcommand.task]]
id = "profile"
label = "Profile a URL"
fields = ["env", "json", "url"]
required = ["url"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["url", "env", "json"]