CLI Reference

Commands

tracemill run

Run a scenario or job and stream generated events.

tracemill run <content-id-or-path>

The run command accepts either a file path or a content ID (see Content ID Resolution below). It inspects the type: field in the YAML to determine whether the file is a scenario or a job.

Use the scenario or job subcommand to explicitly validate the content type:

tracemill run scenario <content-id-or-path>
tracemill run job <content-id-or-path>

Flags:

Destination flags (mutually exclusive — specify at most one group):

When no destination flags are set, events are written to stdout as JSONL (the default).

Event types are auto-discovered from event-types/ directories in the content hierarchy (project > user > library). An emit step referencing an unknown event type is a hard error.

--dry-run uses a manual clock and summary sink — no events are emitted. The summary includes event counts, type breakdown, and estimated duration.

--no-stats suppresses the live statistics overlay. The overlay is shown on stderr when using a remote destination (HEC, S3, TCP, HTTP), or when stdout is redirected to a file/pipe. It is never shown when events go to stdout in a terminal (mixing overlay with event output would be unreadable).

--target-type applies target-specific formatting adjustments. For example, Splunk's Universal Forwarder abbreviates the <System> XML element to <s> in WinEventLog events — --target-type splunk applies this alias so generated events match what Splunk indexes. When --hec-url is set and --target-type is not explicitly provided, the target type is auto-inferred as splunk. Pass --target-type "" to disable inference.

Examples:

# Send events to Splunk via HEC (auto-infers --target-type splunk)
tracemill run job.yaml --hec-url https://splunk:8088 --hec-token my-token

# Send events to a generic HTTP endpoint with explicit Splunk formatting
tracemill run job.yaml --http-url https://proxy:9090 --target-type splunk

# Send events to S3 in CloudTrail format
tracemill run job.yaml --s3-bucket ct-ingest --s3-region us-east-1 --s3-format cloudtrail

# Default: stdout
tracemill run job.yaml

tracemill validate

Parse and validate YAML content files without executing them. Checks for schema errors, undefined references, and unreachable pool configurations.

# Validate a single file
tracemill validate --scenario <path>
tracemill validate --job <path>
tracemill validate --event-type <path>

# Validate all content in a directory recursively
tracemill validate --dir <path>

Exactly one flag is required; they are mutually exclusive.

Flags:

--dir is useful for validating an entire content library in one command:

tracemill validate --dir ./scenarios/
tracemill validate --dir ./event-types/

tracemill list

List available resources.

list generators

List all built-in generators.

tracemill list generators
tracemill list generators --json

list event-types

List all event types discovered from the content hierarchy.

tracemill list event-types
tracemill list event-types --json

Event types are auto-discovered from event-types/ directories in each content layer (project > user > library). The output includes a SOURCE column showing which layer provided each type.

list pools

List all pools defined in a job file.

tracemill list pools --job <path>
tracemill list pools --job <path> --json

The --job flag is required.

All list subcommands accept --json to emit JSON instead of a table.

tracemill schema

Inspect the JSON schemas embedded in the binary.

schema list

Print the names of all available schemas.

tracemill schema list

schema show

Print a schema to stdout.

tracemill schema show <name>
tracemill schema show --all

tracemill version

Print version, commit hash, build date, and Go version.

tracemill version

Global Flags

These flags are available on all commands:

Content ID Resolution

The run command resolves its argument using a three-layer content search. This lets you reference scenarios and jobs by short identifiers instead of full file paths.

Search layers (checked in priority order):

The first layer containing <content-id>.yaml wins. Project-local content shadows library content with the same ID, so you can pin or override a scenario without modifying the shared library.

Examples:

# Content ID — searched across project → user → library
tracemill run aws/scenarios/cloudtrail/brute-force

# File path — used directly, no search
tracemill run ./examples/aws-brute-force.yaml
tracemill run /absolute/path/scenario.yaml
tracemill run ~/scenarios/test.yaml

File path detection: arguments starting with ./, ../, /, or ~ are treated as literal file paths and bypass the content resolver. Arguments ending in .yaml are also treated as file paths, unless they contain . or .. path segments (e.g. aws/../../etc/passwd.yaml), which are rejected as invalid content IDs instead.

Environment Variables

Environment variables use the TRACEMILL_ prefix. They can be set instead of passing flags:

export TRACEMILL_LIBRARY=/path/to/custom/library
tracemill run my-scenario