Telflo Docs

Run telflo <command> --help for the full flag list of any command. This page groups the commands by what they act on.

Global flags and settings

Flag or setting	Effect
`--json`	Print a single JSON document on standard output; diagnostics go to standard error. Accepted by every command.
`--token <tf_...>`, `--api-url <url>`	Override the stored credential and API URL for one command.
`TELFLO_API_TOKEN`, `TELFLO_API_URL`, `TELFLO_APP_URL`	Environment equivalents. `TELFLO_API_URL` defaults to `https://telflo.com`.
`~/.telflo/credentials.json`	The credentials file written by `telflo login`.
`--cli-version`, `-V`	Print the CLI version.

Exit codes are 0 for success, 1 for an API or run error, 2 for a usage error, 3 for an authentication error, and 4 for a failed validation, lint, or test, or a deploy with no published version.

Authentication

Command	What it does
`telflo login`	Opens the Authorize Telflo CLI page in your browser and stores a session for the organization you approve. Reads a pasted login code from the terminal while it waits. Flags: `--app-url`, `--api-url`, `--no-browser` (print the URL and wait for the code), `--code <code>` (finish a login with a copied code).
`telflo login --token <tf_...>`	Stores an API token as the credential, for CI and automation. Accepts `--api-url`.
`telflo whoami`	Prints the organization ID and the identity, plus the granted access for a token credential. JSON output adds the credential kind, `user` or `service_account`.
`telflo logout`	Deletes the local credentials file. It does not revoke a token or end a session elsewhere.

See Overview for the login flows in detail.

Validate

telflo validate <file|-> [--config <id>] [--collector-version <v>] [--distribution <d>]

Validates collector YAML against a real collector binary. With a credential, the CLI uses the authenticated endpoint; without one, it falls back to the anonymous validator that the public editor uses. --config <id> validates on the collector that configuration's latest version is pinned to, and needs a credential. Explicit --collector-version and --distribution flags win over the pin; with neither, the server default is used. With a credential, --distribution accepts otelcol-contrib only; any other value is refused with Unknown collector distribution.

JSON output has valid, version, and errors, each error with a message and a component_path. The command exits 4 when the YAML is invalid, and 1 with could not validate when the validator itself is down or misconfigured: the YAML was not checked.

OTTL lint

telflo ottl lint [file|-] [--context <ctx>] [--kind condition|statement|value] [--expr <ottl>]...

Parses every OTTL expression with the real OTTL grammar. Without --context, the file is a collector configuration and the linter checks every expression in transform (flat or structured statements), filter, the routing connector's table conditions, and tail_sampling policies with ottl_condition, including and and composite sub-policies. Each problem points at a dotted YAML location. With --context, --expr values and the file's non-blank, non-comment lines are raw expressions of the given --kind.

The linter also rejects single-escaped regex sequences such as "\d", which parse but never match. Functions that only the transform processor registers, such as convert_sum_to_gauge, are reported as notes rather than errors, and expressions the linter cannot judge, such as routing rules in the request context, are listed under skipped.

JSON output has valid, ottl_version, checked, items with kind, index, input, valid, error, context, location, and note, and skipped. Exit 4 when any item is invalid, 1 with could not lint when the linter service is unavailable.

Configurations

Command	What it does
`telflo config list`	Lists configurations as a table of ID, name, published version, latest version, and collector. JSON output carries the raw fields, including `is_published`, `version_number`, `published_version_number`, `collector_version`, and `updated_at`.
`telflo config get <id>`	Shows one configuration and its versions, newest first, each with `version_number`, `status` (`draft` or `published`), `description`, and `created_at`.
`telflo config pull <id> [--version <n>] [-o <file>]`	Writes a version's YAML to standard output or a file and reports the collector pin, for example `pinned to clickstack 2.36.0`. JSON output includes `collector_version` and `collector_distribution`.
`telflo config create --name <name> -f <file\|->`	Creates a configuration with the file as its draft version 1. The YAML is stored without validation, and the configuration is locked to OpenTelemetry Collector Contrib.
`telflo config push <id> -f <file\|-> [--publish] [--description <text>]`	Validates the file on the configuration's collector, then edits the latest draft in place or appends a new version when the latest version is published. `--publish` publishes the result. JSON output reports `action` (`patched` or `appended`), `version_number`, and `published`. Exit 4 means the YAML is invalid; exit 1 with `could not validate the configuration (nothing was saved)` means the validator was unavailable, not that the YAML is wrong.
`telflo config publish <id> --version <n>`	Publishes a version. Publishing an already published version succeeds and points the configuration's published version at it again.
`telflo config rules <id> [--version <n>]`	Lists the validation rules saved on a version, grouped by pipeline. See Pipeline tests.

Fleets and deployment

Command	What it does
`telflo fleet list`	Lists fleets with `id`, `label`, `type`, `status`, and `created_at`.
`telflo fleet create --label <label> --type <server-supervisor\|kubernetes-supervisor> [--expires-in 180d\|1y\|2y\|never]`	Creates a fleet and issues its tokens. The label is up to 80 characters and unique in the organization; `--expires-in`, `never` by default, sets the runtime fleet token's lifetime for a server fleet. The output names the connection token's ID; install collectors with `fleet install`.
`telflo fleet deployments <fleet-id>`	Lists the fleet's deploy groups with `id`, `name`, `configuration_id`, `version_number`, `replicas`, `namespace`, and `role`.
`telflo fleet install <fleet-id> --platform <docker\|linux\|kubernetes> [--deployment <id>] [--server-name <name>] [--arch amd64\|arm64] [--root-path <dir>] [--no-systemd] [--env NAME=value]...`	Prints the command that installs a collector into the fleet, composed the same way as the web app's install and deploy dialogs. The command goes to standard output and notes to standard error, so `telflo fleet install ... > install.sh` captures exactly what to run. The CLI does not run it: the collector runs on the target host or cluster.
`telflo deploy --fleet <id> --config <id> [--version <n>] [--deployment <id>] [--name <name>] [--replicas <n>] [--namespace <ns>] [--role <role>]`	Rolls a published version out to a deploy group. Without `--version` it uses the configuration's published version, and fails if there is none. It updates the deploy group already serving that configuration, or the one named by `--deployment`; with `--name` it creates a new group, with `--role` on a Kubernetes supervisor fleet. When several groups serve the configuration, it asks for `--deployment`. JSON output reports `action` (`updated` or `created`), `id`, and `version_number`.

fleet install rules:

docker and linux need a server fleet; kubernetes needs a Kubernetes supervisor fleet. A mismatch is rejected.
A server fleet installs into its Default deploy group unless --deployment names another. A Kubernetes supervisor fleet needs exactly one deploy group or --deployment; otherwise the error lists the candidates. Create the group first with telflo deploy ... --name <name> --role node|cluster|gateway.
linux produces the All In One supervisor bundle command through a Quick Deploy link that is valid for 24 hours, the same as Quick Deploy in the app; --no-systemd runs the supervisor in the foreground instead of installing a service.
--env NAME=value fills a configuration environment variable the same way the install dialog does. In the Docker and Kubernetes commands, a variable the configuration needs but you did not supply appears as a <value> placeholder; the Linux bundle leaves it out, and a note on standard error lists what to set on the host before the supervisor starts. See Install collectors.
For docker and linux, the output embeds the fleet's install token, so treat it like a secret; the kubernetes command instead fetches its values through the expiring URL it contains. A ClickStack deploy group on a Kubernetes supervisor fleet needs the clickhouse.* Helm flags the Deploy dialog adds; the CLI notes this and does not add them.

Flows

Command	What it does
`telflo flows list`	Lists the public flows as a table of slug, name, signals, collector, and who built it, the `by` column. JSON output adds the summary, source, tags, and timestamps, without YAML.
`telflo flows get <slug>`	The same for one flow, plus its description and YAML.
`telflo flows pull <slug> [-o <file>]`	Writes the flow's YAML to standard output or a file, ready for `telflo config create`. An unknown slug exits 1.

Creating a configuration from a flow with config create does not pin the flow's collector version, and creates the configuration on OpenTelemetry Collector Contrib even for a flow validated on another distribution. Set the collector version in the app if it matters.

Test

telflo test --spec <spec.yaml> (--config <id> [--version <n>] | -f <file> [--config <id>]) [--collector-version <v>] [--distribution <d>] [--save | --saved] [--output <file>] [--timeout <s>]

Submits a pipeline test to the Telflo testing sandbox and polls until it finishes, every second at first and every five seconds after the first ten polls, for up to the spec's duration plus two minutes unless --timeout says otherwise. --config tests a stored version on its collector pin; -f tests a local file, on the configuration's pin when --config is also given and on the server default otherwise. Flags beat everything; on a local file with -f and --config together, the configuration's pin fills in what the flags leave unset and beats the spec's collector_version and distribution fields, while a stored-version run takes the spec's fields over the version's own pin. --save and --saved need --config and are a usage error with -f. Exit 0 when the run succeeds, 4 when an assertion fails, 1 on an error or timeout. The spec format is on Pipeline tests.

Skills

Command	What it does
`telflo skills install [--project \| --global]`	Copies the bundled agent skill into `./.claude/skills/` (the default) or `~/.claude/skills/`.

Commands