CLI Reference

Command-line interface reference for Telegen.

Synopsis

telegen [command] [flags]

Global Flags

Flag	Short	Description	Default
`--config`	`-c`	Config file path	`/etc/telegen/config.yaml`
`--log-level`	`-l`	Log level (debug, info, warn, error)	`info`
`--log-format`		Log format (json, text)	`json`
`--help`	`-h`	Show help
`--version`	`-v`	Show version

Commands

telegen

Run Telegen agent or collector.

telegen [flags]

Examples:

# Run with default config
telegen

# Run with custom config
telegen --config /path/to/config.yaml

# Run with debug logging
telegen --log-level debug

# Run with environment variable config
TELEGEN_CONFIG_FILE=/path/to/config.yaml telegen

Flags:

Flag	Description	Default
`--config`	Path to configuration file	`/etc/telegen/config.yaml`
`--mode`	Operating mode (agent, collector)	`agent`

telegen version

Display version information.

telegen version [flags]

Examples:

# Short version
telegen version

# Detailed version
telegen version --long

Output:

telegen version 3.0.0
  commit: abc1234
  built: 2024-01-15T10:00:00Z
  go: go1.21.5

Flags:

Flag	Description
`--long`	Show detailed version info
`--json`	Output as JSON

telegen validate

Validate configuration file.

telegen validate [flags]

Examples:

# Validate default config
telegen validate

# Validate specific file
telegen validate --config /path/to/config.yaml

# Validate and show parsed config
telegen validate --show

Flags:

Flag	Description
`--config`	Config file to validate
`--show`	Show parsed configuration
`--strict`	Enable strict validation

Output:

✓ Configuration is valid

Parsed configuration:
  Mode: agent
  OTLP Endpoint: otel-collector:4317
  eBPF: enabled
  Profiling: enabled

telegen diagnostics

Collect diagnostic information.

telegen diagnostics [flags]

Examples:

# Create diagnostic bundle
telegen diagnostics > diagnostics.tar.gz

# Output to specific file
telegen diagnostics --output /tmp/telegen-diag.tar.gz

# Include sensitive data (use with caution)
telegen diagnostics --include-config

Flags:

Flag	Description
`--output`	Output file path
`--include-config`	Include config (may contain secrets)
`--include-logs`	Include recent logs

Bundle Contents:

System information (kernel, distro, arch)
Telegen version and build info
eBPF program list
Metrics snapshot
Configuration (sanitized unless --include-config)
Recent logs (if --include-logs)

telegen completion

Generate shell completion scripts.

telegen completion [shell] [flags]

Supported Shells:

bash
zsh
fish
powershell

Examples:

# Bash completion
telegen completion bash > /etc/bash_completion.d/telegen

# Zsh completion
telegen completion zsh > "${fpath[1]}/_telegen"

# Fish completion
telegen completion fish > ~/.config/fish/completions/telegen.fish

Environment Variables

Configuration can be set via environment variables.

Core Settings

Variable	Description	Example
`TELEGEN_CONFIG_FILE`	Config file path	`/etc/telegen/config.yaml`
`TELEGEN_MODE`	Operating mode	`agent`
`TELEGEN_LOG_LEVEL`	Log level	`info`
`TELEGEN_LOG_FORMAT`	Log format	`json`

OTLP Settings

Variable	Description	Example
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP endpoint	`otel-collector:4317`
`OTEL_EXPORTER_OTLP_HEADERS`	OTLP headers	`Authorization=Bearer token`
`OTEL_EXPORTER_OTLP_INSECURE`	Skip TLS verification	`true`
`OTEL_EXPORTER_OTLP_COMPRESSION`	Compression	`gzip`

Resource Attributes

Variable	Description	Example
`OTEL_SERVICE_NAME`	Service name	`my-service`
`OTEL_RESOURCE_ATTRIBUTES`	Resource attributes	`env=prod,version=1.0`

Feature Flags

Variable	Description	Example
`TELEGEN_AGENT_EBPF_ENABLED`	Enable eBPF	`true`
`TELEGEN_AGENT_PROFILING_ENABLED`	Enable profiling	`true`
`TELEGEN_AGENT_SECURITY_ENABLED`	Enable security	`true`
`TELEGEN_AGENT_NETWORK_ENABLED`	Enable network	`true`

Kubernetes

Variable	Description	Example
`POD_NAME`	Pod name	`telegen-abc123`
`POD_NAMESPACE`	Pod namespace	`monitoring`
`POD_UID`	Pod UID	`550a8ab5-...`
`NODE_NAME`	Node name	`node-1`
`KUBERNETES_SERVICE_HOST`	K8s API host	`10.0.0.1`
`KUBERNETES_SERVICE_PORT`	K8s API port	`443`

Exit Codes

Code	Description
0	Success
1	General error
2	Configuration error
3	eBPF initialization error
4	Permission error
5	Export error

Signal Handling

Signal	Action
`SIGTERM`	Graceful shutdown
`SIGINT`	Graceful shutdown
`SIGHUP`	Reload configuration
`SIGUSR1`	Dump status to logs

Examples:

# Graceful shutdown
kill -TERM $(pidof telegen)

# Reload configuration
kill -HUP $(pidof telegen)

# Dump status
kill -USR1 $(pidof telegen)

Debugging

Enable Debug Logging

# Via flag
telegen --log-level debug

# Via environment
TELEGEN_LOG_LEVEL=debug telegen

# In config
telegen:
  log_level: debug

eBPF Debugging

# Enable eBPF debug output
TELEGEN_AGENT_EBPF_DEBUG=true telegen --log-level debug

# Check loaded programs
bpftool prog list | grep telegen

# View eBPF maps
bpftool map list | grep telegen

# Trace eBPF output
cat /sys/kernel/debug/tracing/trace_pipe

Dry Run

# Validate config without starting
telegen validate --config /path/to/config.yaml

# Show effective configuration
telegen validate --show

Examples

Basic Agent

telegen --config /etc/telegen/config.yaml

With Custom Endpoint

OTEL_EXPORTER_OTLP_ENDPOINT=my-collector:4317 telegen

Debug Mode

telegen --log-level debug --log-format text

Collector Mode

telegen --mode collector --config /etc/telegen/collector.yaml

Docker Run

docker run -d \
  --name telegen \
  --privileged \
  --pid=host \
  --network=host \
  -v /sys:/sys:ro \
  -v /proc:/host/proc:ro \
  -v /sys/kernel/debug:/sys/kernel/debug \
  -v /sys/fs/bpf:/sys/fs/bpf \
  -v /etc/telegen:/etc/telegen:ro \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:4317 \
  ghcr.io/mirastacklabs-ai/telegen:latest

Next Steps

API Reference - REST API endpoints
Full Configuration Reference - Configuration options
Troubleshooting - Troubleshooting guide