Telflo Docs

Push, validate, test, and deploy collector configurations from your terminal, your CI pipeline, or an AI coding agent.

The Telflo CLI, telflo, works with your organization's configurations, fleets, and flows from the command line. It talks to the same Telflo API as any other client, so a configuration you push from the terminal appears in the web app at once, and the collector distribution and version pinned on a configuration apply to CLI validation and tests too.

The CLI is another client of the same control plane. A terminal signed in as you, a CI pipeline holding an organization API token, and an AI coding agent all reach one organization's configurations and fleets. Collectors still pull their configuration and report their status back.

Install

The CLI is an npm package and needs Node.js 20 or newer.

npm install -g telflo
telflo --cli-version

To run it without installing, prefix a command with npx, for example npx telflo login.

telflo --cli-version prints the CLI's own version. The --version <n> flag on config pull, config publish, deploy, and test always means a configuration version number, and a bare telflo --version is a usage error.

telflo login

Your browser opens the Authorize Telflo CLI page, which names the account the CLI will sign in as; sign in to Telflo first if you are not already. If you belong to more than one organization, choose the one to work in under Organization, then select Continue as followed by your email address. The CLI, which waits up to five minutes for the approval, now acts as you in that organization: configurations you create or edit appear in the web app immediately, exactly as if you had made the change there. To switch organizations, run telflo login again.

Some browsers, notably Safari and Brave, refuse to hand the session back to a program on your machine. When that happens, the page shows a Login code under Paste this code into your terminal. Paste it into the terminal that is still running telflo login and press Enter. The code works once and expires shortly; if the terminal has already given up, run telflo login again and use the new code.

Two flags cover a machine without a browser, such as a remote or SSH session:

telflo login --no-browser

prints the login URL for you to open anywhere, then waits for the code, and

telflo login --code <code>

finishes a login with a code you already copied.

A browser-login session ends when you sign out of Telflo or when it expires.

CI pipelines and other automation authenticate with a token from a service account instead of a person's session. An organization admin creates the service account under Settings > Service Accounts and adds a token to it, read-only for pipelines that only validate and read, or read and write for pipelines that test, push, and deploy. Set two environment variables and no login step is needed:

export TELFLO_API_TOKEN=tf_...
export TELFLO_API_URL=https://telflo.com

TELFLO_API_URL is optional; https://telflo.com is the default. To store a token on a workstation instead, run telflo login --token tf_..., which checks the token and saves it. Credentials are resolved in this order: the --token and --api-url flags, then the environment variables, then the credentials file, then the default URL. A token given by flag or environment variable wins over a stored browser session.

Changes made with a token are attributed to the service account, not to a person, and its unpublished drafts are visible to teammates only once a configuration is published.

An organization admin can also obtain a token during telflo login. The Authorize Telflo CLI page shows Use a CI token instead to admins; selecting it opens the Use a CI token form, which sends a token for the chosen organization to the waiting CLI:

Choose the Service account the token belongs to. If the organization has none, the form says so and links to Settings → Service Accounts; create one there and run telflo login again.
Under Token, either select Add new token or pick an existing token, listed by name, prefix, access, and last use.
For a new token, enter a Token name, prefilled with the CLI's name and the current date and time, choose Read & write or Read only under Access, and set Expires in (days, 0 = never), 90 by default. Minting a token this way requires you to be an admin of the selected organization.
For an existing token, paste its value under Paste the token. Telflo checks that the value matches the token you picked; a token's value is never shown again after creation, so this path only confirms a value you already hold.
Select Approve. The CLI stores the token as its credential. When a new token was minted, the You're logged in page also shows its value once, with a copy button, in case a CI job needs it too. When an existing token was picked, the page confirms it was not changed and nothing new was created; abandoning the login at that point needs no cleanup, and the token stays valid for whatever else uses it.

Check who the CLI acts as

telflo whoami

prints, for a browser session, your email address and the organization ID with acting as: you; and for a token, the organization ID, the token's name, and its access. With --json, the credential kind is user or service_account.

Credentials on disk

The CLI stores its credential in ~/.telflo/credentials.json, readable only by your user. telflo logout deletes that file and nothing else: to revoke an API token, delete it on its service account's page under Settings > Service Accounts.

Quick start

The terminal equivalent of the build, test, publish, and deploy path. Each stage is a single command, and each one exits non-zero when it fails, so the loop runs unattended in CI.

telflo config list                            # find a configuration ID
telflo config pull <id> -o config.yaml        # download its latest YAML and collector pin
# edit config.yaml
telflo validate config.yaml --config <id>     # validate on that configuration's collector
telflo config push <id> -f config.yaml --publish
telflo test --spec test.yaml --config <id>    # run a pipeline test against a sample
telflo deploy --fleet <fleet-id> --config <id>

Every configuration is locked to a collector distribution, and its versions can pin a collector version; without a pin, the server's default collector version is used. Commands that target a stored configuration, such as push and test --config, run on that pin automatically. When you validate or test a local file, pass --config <id> so it runs on the same collector; without it, telflo test uses the spec's collector_version and distribution fields when set, and otherwise the server default is used. --collector-version and --distribution override either.

config push edits the latest draft in place when it is unpublished, and appends a new version when the latest version is already published. Published versions cannot be changed. See Versions & publishing.

The API, and so the CLI, currently offers only OpenTelemetry Collector Contrib: config create locks a new configuration to it, and --distribution accepts otelcol-contrib only. A configuration locked to ClickStack in the app keeps its pin: telflo test --config <id> runs on it, because the API inherits the stored version's distribution, but telflo validate --config <id> and telflo test -f <file> --config <id> name that distribution explicitly and are refused for such a configuration.

Output and exit codes

Every command accepts --json. With it, standard output is a single JSON document and diagnostics go to standard error, so a script can parse one and log the other.

Exit code	Meaning
0	Success.
1	An API or run error, including a validator or test sandbox that is unavailable.
2	A usage error.
3	An authentication error: sign in again, or the token is read-only, expired, or revoked.
4	Validation failed, a test assertion failed, an OTTL lint found problems, or a deploy found no published version.

AI coding agents

The CLI bundles a skill that teaches agents such as Claude Code how to use it: the edit, validate, push, test, and deploy loop, how to write test specs, and how to read results.

telflo skills install            # into ./.claude/skills/ for this project
telflo skills install --global   # into ~/.claude/skills/ for every project

Give the agent a read and write token through TELFLO_API_TOKEN, or run telflo login yourself first so the agent works as you. To give an agent the same operations as tools, with nothing to install, connect it to the MCP server instead. The AI assistant in the editor is separate and needs no CLI.

Continue with the command reference and pipeline tests from the CLI.

Overview