CLI Commands Reference

This reference covers all commands available in the tmpnetctl CLI tool.

Global Flags

These flags are available for all commands:

Flag	Description	Default
`--network-dir`	Path to an existing network (used by stop-network and restart-network)	`$TMPNET_NETWORK_DIR` if set
`--log-format`	Logging format (auto, plain, colors, json)	`auto`
`--help, -h`	Show help

Network Commands

start-network

Start a new temporary network.

tmpnetctl start-network [flags]

Flags:

Flag	Type	Description	Default
`--avalanchego-path`	string	Path to avalanchego binary	`$AVALANCHEGO_PATH` (required)
`--plugin-dir`	string	Directory containing VM plugins	`$AVAGO_PLUGIN_DIR` or `~/.avalanchego/plugins`
`--node-count`	int	Number of validator nodes	`2`
`--network-owner`	string	Owner identifier for the network (added to the network directory name)	empty
`--root-network-dir`	string	Root directory for networks	`$TMPNET_ROOT_NETWORK_DIR`, else `~/.tmpnet/networks`
`--runtime`	string	Node runtime: `process` or `kube`	`process`
`--reuse-dynamic-ports`	bool	Reuse the dynamic API port when a node restarts (process runtime)	`false`
`--kube-*`		Kube runtime settings (namespace, image, volume size, scheduling)	See `tmpnetctl start-network --help`

Example:

# Start default 2-node network
tmpnetctl start-network --avalanchego-path=./bin/avalanchego

# Start 3-node network
tmpnetctl start-network --avalanchego-path=./bin/avalanchego --node-count=3

# Custom plugin directory
tmpnetctl start-network \
  --avalanchego-path=./bin/avalanchego \
  --plugin-dir=/custom/plugins

Output:

[...] INFO waiting for network to start {"timeoutSeconds": 120}
...
[...] INFO started network {"networkDir": "/home/user/.tmpnet/networks/20240312-143052.123456", "uuid": "abc-123..."}
...

Configure tmpnetctl to target this network by default with one of the following statements:
 - source /home/user/.tmpnet/networks/20240312-143052.123456/network.env
 - export TMPNET_NETWORK_DIR=/home/user/.tmpnet/networks/20240312-143052.123456
 - export TMPNET_NETWORK_DIR=/home/user/.tmpnet/networks/latest

stop-network

Stop a running network.

tmpnetctl stop-network [flags]

Flags:

Flag	Type	Description	Default
`--network-dir`	string	Network directory to stop	`$TMPNET_NETWORK_DIR` (required)

Example:

# Stop using TMPNET_NETWORK_DIR
export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest
tmpnetctl stop-network

# Stop with explicit path
tmpnetctl stop-network --network-dir=~/.tmpnet/networks/20240312-143052.123456

restart-network

Restart the running nodes of a network. Stopped nodes stay stopped, so this command does not start a network after stop-network.

tmpnetctl restart-network [flags]

Flags:

Flag	Type	Description	Default
`--network-dir`	string	Network directory to restart	`$TMPNET_NETWORK_DIR` (required)

Example:

# Restart using TMPNET_NETWORK_DIR
tmpnetctl restart-network

# Restart with explicit path
tmpnetctl restart-network --network-dir=~/.tmpnet/networks/latest

Monitoring Commands

start-metrics-collector

Start Prometheus to collect metrics from networks.

tmpnetctl start-metrics-collector [flags]

Required Environment Variables:

PROMETHEUS_URL - Prometheus query URL (optional here; check-metrics uses it)
PROMETHEUS_PUSH_URL - Prometheus push URL
PROMETHEUS_USERNAME - Username for authentication
PROMETHEUS_PASSWORD - Password for authentication

Example:

# Set environment variables
export PROMETHEUS_URL="https://prometheus.example.com"
export PROMETHEUS_PUSH_URL="https://prometheus.example.com/api/v1/push"
export PROMETHEUS_USERNAME="user"
export PROMETHEUS_PASSWORD="pass"

# Start collector
tmpnetctl start-metrics-collector

Output:

...
[...] INFO To stop: tmpnetctl stop-metrics-collector

stop-metrics-collector

Stop the running Prometheus metrics collector.

tmpnetctl stop-metrics-collector

Example:

tmpnetctl stop-metrics-collector

start-logs-collector

Start Promtail to collect logs from networks.

tmpnetctl start-logs-collector [flags]

Required Environment Variables:

LOKI_URL - Loki query URL (optional here; check-logs uses it)
LOKI_PUSH_URL - Loki push URL
LOKI_USERNAME - Username for authentication
LOKI_PASSWORD - Password for authentication

Example:

# Set environment variables
export LOKI_URL="https://loki.example.com"
export LOKI_PUSH_URL="https://loki.example.com/loki/api/v1/push"
export LOKI_USERNAME="user"
export LOKI_PASSWORD="pass"

# Start collector
tmpnetctl start-logs-collector

stop-logs-collector

Stop the running Promtail logs collector.

tmpnetctl stop-logs-collector

Example:

tmpnetctl stop-logs-collector

check-metrics

Verify that metrics are being collected for a network.

tmpnetctl check-metrics [flags]

Flags:

Flag	Type	Description	Default
`--network-uuid`	string	UUID of the network to check (the `uuid` field of `[network-dir]/config.json`). If not set, the command uses the `GH_*` env vars of a GitHub Actions run and fails if none is set.	empty

Required Environment Variables:

PROMETHEUS_URL
PROMETHEUS_USERNAME
PROMETHEUS_PASSWORD

Example:

tmpnetctl check-metrics --network-uuid="$(jq -r '.uuid' ~/.tmpnet/networks/latest/config.json)"

Output:

[...] INFO checking if metrics exist {"url": "https://prometheus.example.com", "query": "count({network_uuid=\"abc-123...\"})"}
[...] INFO collected count is non-zero {"type": "metrics", "count": 42}

check-logs

Verify that logs are being collected for a network.

tmpnetctl check-logs [flags]

Flags:

Flag	Type	Description	Default
`--network-uuid`	string	UUID of the network to check (the `uuid` field of `[network-dir]/config.json`). If not set, the command uses the `GH_*` env vars of a GitHub Actions run and fails if none is set.	empty

Required Environment Variables:

LOKI_URL
LOKI_USERNAME
LOKI_PASSWORD

Example:

tmpnetctl check-logs --network-uuid="$(jq -r '.uuid' ~/.tmpnet/networks/latest/config.json)"

Kubernetes Commands

start-kind-cluster

Start a local kind (Kubernetes in Docker) cluster for tmpnet.

tmpnetctl start-kind-cluster [flags]

Flags:

Flag	Type	Description	Default
`--kubeconfig`	string	Path to kubeconfig file	`~/.kube/config`
`--start-metrics-collector`	bool	Start metrics collector	`false`
`--start-logs-collector`	bool	Start logs collector	`false`
`--install-chaos-mesh`	bool	Install Chaos Mesh	`false`

Example:

# Start basic kind cluster
tmpnetctl start-kind-cluster

# Start with monitoring
tmpnetctl start-kind-cluster \
  --start-metrics-collector \
  --start-logs-collector

# Start with Chaos Mesh for chaos engineering
tmpnetctl start-kind-cluster --install-chaos-mesh

Utility Commands

version

Print tmpnetctl version information.

tmpnetctl version

Example:

tmpnetctl version

Output:

0.0.1, commit=<git commit>

help

Show help for tmpnetctl or a specific command.

tmpnetctl help [command]

Example:

# General help
tmpnetctl help

# Help for specific command
tmpnetctl help start-network

Common Usage Patterns

Setting Up a Network

Complete workflow for creating and using a network:

# Build binaries
./scripts/build.sh
./scripts/build_tmpnetctl.sh

# Start network
tmpnetctl start-network --avalanchego-path=./bin/avalanchego

# Configure shell
export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest

# Use the network...

# Stop when done
tmpnetctl stop-network

Using with direnv

Simplify commands with direnv:

# Enable direnv
cd avalanchego
direnv allow

# Now you can use simplified commands
tmpnetctl start-network        # No --avalanchego-path needed
tmpnetctl stop-network
tmpnetctl restart-network

Monitoring Workflow

Set up monitoring for development:

# Configure monitoring environment
export PROMETHEUS_URL="..."
export PROMETHEUS_PUSH_URL="..."
export PROMETHEUS_USERNAME="..."
export PROMETHEUS_PASSWORD="..."
export LOKI_URL="..."
export LOKI_PUSH_URL="..."
export LOKI_USERNAME="..."
export LOKI_PASSWORD="..."

# Start collectors once
tmpnetctl start-metrics-collector
tmpnetctl start-logs-collector

# Create/destroy networks as needed
tmpnetctl start-network --avalanchego-path=./bin/avalanchego
# ... test ...
tmpnetctl stop-network

# Collectors continue running
# Stop when done
tmpnetctl stop-metrics-collector
tmpnetctl stop-logs-collector

Multiple Networks

Manage multiple networks:

# Start first network
tmpnetctl start-network --avalanchego-path=./bin/avalanchego
NETWORK1=~/.tmpnet/networks/$(readlink ~/.tmpnet/networks/latest)

# Start second network
tmpnetctl start-network --avalanchego-path=./bin/avalanchego
NETWORK2=~/.tmpnet/networks/$(readlink ~/.tmpnet/networks/latest)

# Target specific networks
tmpnetctl stop-network --network-dir=$NETWORK1
tmpnetctl restart-network --network-dir=$NETWORK2

Environment Configuration

Recommended Shell Setup

Add to your .bashrc or .zshrc:

# Set default network to latest
export TMPNET_NETWORK_DIR=~/.tmpnet/networks/latest

# Set avalanchego path
export AVALANCHEGO_PATH=~/avalanchego/bin/avalanchego

# Add tmpnetctl to PATH (if not using direnv)
export PATH=$PATH:~/avalanchego/bin

Monitoring Environment

Create a monitoring env file:

# monitoring.env
export PROMETHEUS_URL="https://prometheus.example.com"
export PROMETHEUS_PUSH_URL="https://prometheus.example.com/api/v1/push"
export PROMETHEUS_USERNAME="user"
export PROMETHEUS_PASSWORD="pass"
export LOKI_URL="https://loki.example.com"
export LOKI_PUSH_URL="https://loki.example.com/loki/api/v1/push"
export LOKI_USERNAME="user"
export LOKI_PASSWORD="pass"

Source when needed:

source monitoring.env
tmpnetctl start-metrics-collector
tmpnetctl start-logs-collector

Exit Codes

tmpnetctl uses standard exit codes:

0 - Success
1 - Any error, including invalid flags or arguments

Error Handling

Common Errors

Network directory not found:

Error: --network-dir or TMPNET_NETWORK_DIR is required

If the directory does not exist:

Error: lstat /path/to/network: no such file or directory

Solution: Check that TMPNET_NETWORK_DIR is set correctly or provide --network-dir

Binary not found:

Error: failed to configure process runtime: --avalanchego-path (/path/to/avalanchego) not found: stat /path/to/avalanchego: no such file or directory

Solution: Verify --avalanchego-path points to a valid binary

Port already in use:

Error: failed to start node: address already in use

Solution: Stop conflicting processes or use dynamic ports (default)

Missing monitoring credentials:

Error: PROMETHEUS_PUSH_URL env var not set

Solution: Set required environment variables for monitoring

Global Flags

Network Commands

start-network

stop-network

restart-network

Monitoring Commands

start-metrics-collector

stop-metrics-collector

start-logs-collector

stop-logs-collector

check-metrics

check-logs

Kubernetes Commands

start-kind-cluster

Utility Commands

version

help

Common Usage Patterns

Setting Up a Network

Using with direnv

Monitoring Workflow

Multiple Networks

Environment Configuration

Recommended Shell Setup

Monitoring Environment

Exit Codes

Error Handling

Common Errors

See Also

On this page