Create a package

This guide shows you how to create a package from scratch. You’ll learn how to set up the directory structure, write the manifest, and add runnable examples.

Create the package scaffold

Create a directory with the standard package layout:

Directoryacme/
- Directorychangelog/ User-facing documentation of changes
  - …
- Directoryexamples/ Runnable snippets for users
  - …
- Directoryoperators/ Reusable building blocks for pipelines
  - …
- Directorypipelines/ Deployable pipelines
  - …
- Directorytests/ Integration tests
  - Directoryinputs/ Sample data for test pipelines
    …
- package.yaml Manifest: metadata, contexts, and inputs

The tests/inputs/ directory holds sample data that the test harness makes available via the TENZIR_INPUTS environment variable. Reference these files from test pipelines using f"{env("TENZIR_INPUTS")}/filename.txt".

Add the package manifest

The package.yaml file is the package manifest. It identifies the directory as a package and contains metadata, context definitions, and input specifications.

Add descriptive metadata

Start with the required and recommended metadata fields:

# The unique ID of the package. (required)
id: acme

# The display name of the package and a path to an icon for the package.
name: My Package
package_icon: https://example.com/icon.svg

# The display name of the package author and a path to a profile picture.
author: Your Name
author_icon: https://github.com/yourusername.png

# A user-facing description of the package.
description: |
  A brief description of what your package does and the use cases it supports.
  You can use **Markdown** formatting here.

Define inputs

Inputs provide a templating mechanism that replaces variables with user-provided values during installation. This makes packages configurable without modifying source files.

inputs:
  refresh_interval:
    name: Refresh Interval
    description: How often the pipeline refreshes the data source.
    default: 1h

Reference inputs using {{ inputs.input-id }} syntax. See Configure inputs for the complete templating guide.

Add examples

The examples directory contains self-contained code snippets that demonstrate how to use the package. These snippets appear in the Tenzir Library and provide runnable TQL code that users can execute after installing the package.

Create example files that showcase your package’s features:

// Demonstrate the primary use case
acme::fetch
acme::transform
head 10

For more complex scenarios, combine multiple operators and show how they work together:

// Show a more complex scenario
acme::fetch
where severity == "high"
acme::enrich
publish "alerts"

Keep examples focused and self-contained. Each example should demonstrate a single concept or use case.

Define contexts

If your package uses enrichment contexts, add a contexts key to the manifest. See Add contexts for the full schema and usage details.