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

Option Description
--dir <DIR> Project directory to use.
--config <FILE> Path to tenzir.toml.
--workspace <ID> Workspace ID to target.
--node <ID> Node ID to target.
--yes Skip confirmation prompts.
--output text|json Output format.
-v, --verbose Increase logging verbosity.
--api-endpoint <URL> Override the platform API endpoint.

Project links

Data verified by PyPI on Jul 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for aljazerzen from gravatar.com aljazerzen

Credits

Author: Tenzir

GitHub Statistics

Data verified by PyPI on Jul 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.8

Tags

tenzir pipeline cli platform security

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tzctl-0.2.0.tar.gz (114.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

tzctl-0.2.0-py3-none-win_amd64.whl (3.8 MB view details)

Uploaded Python 3Windows x86-64

tzctl-0.2.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.8 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

tzctl-0.2.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.6 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

tzctl-0.2.0-py3-none-macosx_11_0_arm64.whl (3.5 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

File details

Details for the file tzctl-0.2.0.tar.gz.

File metadata

  • Download URL: tzctl-0.2.0.tar.gz
  • Upload date:
  • Size: 114.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for tzctl-0.2.0.tar.gz
Algorithm Hash digest
SHA256 4a623ea4a669c79c64fff77db766fef1eebd8d4c5f522123a6d2dcf844fefaa0
MD5 3b62650c90c50a05f48b6a188b61e822
BLAKE2b-256 79ba337f58cbb5a8257d3eb9401a0cefc50c1e000e5097b2db2b833e59fbdf07

See more details on using hashes here.

Provenance

The following attestation bundles were made for tzctl-0.2.0.tar.gz:

Publisher: release.yml on tenzir/tzctl

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tzctl-0.2.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: tzctl-0.2.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 3.8 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for tzctl-0.2.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 31bd85d3b0db5b9371f0eaa3ccb659898484901857db9a10161e286e1faf67cf
MD5 c9ddeb91039aeb0760462df56f94f56e
BLAKE2b-256 8eb9855aa716ea5e827d2755ab9b719b746a5eb14717e6114c69ebbbc93197af

See more details on using hashes here.

Provenance

The following attestation bundles were made for tzctl-0.2.0-py3-none-win_amd64.whl:

Publisher: release.yml on tenzir/tzctl

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tzctl-0.2.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for tzctl-0.2.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 de146df2b653c9c8dcff62d74223d63ad8e3bb49baed122ba565f9af0d58fed2
MD5 37aedae7dff00cdc557448b22e55fc1f
BLAKE2b-256 fa84aa87451c77c6de621a4ba7d9ec69e907466513f3cbfcd70b90abe5bdd445

See more details on using hashes here.

Provenance

The following attestation bundles were made for tzctl-0.2.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on tenzir/tzctl

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tzctl-0.2.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for tzctl-0.2.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 cd33762f240adb964e54d52a282597d4ce15c0058b12814d83861b421117c3db
MD5 fe408f394e62fac245cd01132862febe
BLAKE2b-256 2d5f53be302f9861ccd95c4d92bead34f036fd34df59e93e022e1b20c0e30bed

See more details on using hashes here.

Provenance

The following attestation bundles were made for tzctl-0.2.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on tenzir/tzctl

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tzctl-0.2.0-py3-none-macosx_11_0_arm64.whl.

File metadata

  • Download URL: tzctl-0.2.0-py3-none-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 3.5 MB
  • Tags: Python 3, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for tzctl-0.2.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f9ec1c074ac438182a4e1283f89017412fcbd37ec10a54bef031df4055e5a17e
MD5 d116b76099e04c9cc73a581f93bff844
BLAKE2b-256 dc32e8f2d853de98f4c04331d56d9dc866938e636c865c930b29d990b1920201

See more details on using hashes here.

Provenance

The following attestation bundles were made for tzctl-0.2.0-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on tenzir/tzctl

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.0 This release

5 files

0.1.0

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page