tzctl

tzctl manages Tenzir pipelines on a remote node through the Tenzir Platform. It treats a local directory of .tql files as the source of truth, compares that desired state with the pipelines that already exist on a node, and then shows or applies the changes needed to bring them back in sync.

What you can do with tzctl

• Sign in to the Tenzir Platform.
• List workspaces, nodes, and pipelines.
• Create, update, start, stop, and delete individual pipelines.
• Inspect a pipeline's diagnostics and throughput with pipeline status.
• Run a .tql file or inline TQL ad hoc and stream results (stdout) and diagnostics (stderr) to your terminal with run.
• Plan and apply declarative changes from a local project.
• Export machine-readable output with --output json.

How it works

A tzctl project is a directory of .tql files plus a tenzir.toml configuration file.

• Each .tql file defines one pipeline.
• tzctl project apply creates, updates, deletes, or changes pipeline state to match your files.
• tzctl project pull fetches pipeline definitions from the platform and writes them back into your project as .tql files.

Installation

uvx tzctl
uv tool install tzctl
cargo install tzctl
nix run github:tenzir/tzctl -- --help
nix profile add github:tenzir/tzctl

Quick start

1. Authenticate:

   tzctl auth login
   

2. Select the target workspace and inspect available nodes:

   tzctl workspace list
   tzctl workspace select <workspace>
   tzctl node list
   

3. Configure your project in tenzir.toml:

   [workspace]
   id = "t-abcd1234"
   
   [node]
   id = "n-w2tjezz3"
   
   [pipelines]
   glob = "pipelines/**/*.tql"
   
   [defaults]
   state = "running"
   

4. Review changes before applying them:

   tzctl project plan
   

5. Apply the project:

   tzctl project apply
   

Common commands

tzctl auth login
tzctl auth logout

tzctl workspace list
tzctl workspace select <id|name|#>
tzctl node list

tzctl pipeline list
tzctl pipeline create path/to/pipeline.tql
tzctl pipeline set path/to/pipeline.tql
tzctl pipeline start <name>
tzctl pipeline stop <name>
tzctl pipeline delete <name>
tzctl pipeline status <name>
tzctl pipeline status <name> --range 7d --limit 50

tzctl run --file path/to/query.tql
tzctl run -f path/to/query.tql
tzctl run --code 'version'
tzctl run -c 'from {x: 1, y: 2}'

tzctl project plan
tzctl project apply
tzctl project apply --dry-run
tzctl project apply --prune
tzctl project pull
tzctl project pull --prune
tzctl project pull --dry-run
tzctl project destroy

Run tzctl --help for the full command reference.

Declarative pipeline projects

tzctl is most useful when you manage pipelines declaratively.

In this model, your repository contains the desired pipeline definitions and states. tzctl compares that local project with the current node state and reconciles the difference.

This approach helps you:

• Review changes before applying them.
• Keep pipeline definitions in version control.
• Reapply the same state safely and idempotently.
• Avoid accidental drift between environments.

Pipeline files

A pipeline file can contain optional YAML frontmatter in line comments:

// ---
// name: zeek-import
// description: Import Zeek logs
// state: running
// ---
from file "/var/log/zeek/conn.log"
read zeek-tsv

Supported frontmatter fields:

• name
• description
• state (running, paused, or stopped)
• node

If a file has no frontmatter, tzctl uses the file stem as the pipeline name.

Configuration

tzctl reads configuration from tenzir.toml and resolves values in this order:

CLI flags → TENZIR_PLATFORM_CLI_* environment variables → tenzir.toml → built-in defaults

Example:

[platform]
api_endpoint = "https://rest.tenzir.app/production-v1"

[platform.oidc]
client_id = "vzRh8grIVu1bwutvZbbpBDCOvSzN8AXh"
# client_secret_file = "/run/secrets/tenzir-client-secret"

[workspace]
id = "t-abcd1234"

[node]
id = "n-w2tjezz3"

[pipelines]
glob = "pipelines/**/*.tql"

[defaults]
state = "running"

Authentication

tzctl auth login authenticates with the Tenzir Platform and caches the token for later commands.

You can authenticate in these ways:

• Interactive device-code login.
• Non-interactive client-credentials login through tenzir.toml.
• A pre-supplied token from configuration or environment variables.

Safety and output

• tzctl project plan is read-only.
• Destructive actions prompt for confirmation unless you pass --yes.
• --prune deletes pipelines that exist on the node but not in your project.
• --output json prints structured output for automation and CI.

Global options