Welcome to the Wake Guide

Use Wake to tail logs from Kubernetes pods. This is the default mode and provides a straightforward stream of log data.

# Tail logs for kube-proxy in kube-system namespace
wake -n kube-system "kube-proxy"

# Tail logs across all namespaces, including the string 'error'
wake -A -i "error"

This section provides a complete list of all available command-line arguments for Wake.

Argument	Description	Default
POD_SELECTOR	Pod selector regex (positional)	.*
-c, --container <REGEX>	Container selector regex	.*
-s, --sample <N>	Randomly sample up to N matching pods	all
-L, --list-containers	List all containers in matched pods (no streaming)	-
--all-containers	Show logs from all containers in pods	-
-n, --namespace <NAME>	Kubernetes namespace	current context
-A, --all-namespaces	Show logs from all namespaces	-
-k, --kubeconfig <PATH>	Path to kubeconfig file	-
-x, --context <NAME>	Kubernetes context to use	-
-t, --tail <LINES>	Lines of logs to display from beginning	10
-f, --follow [true|false]	Follow logs (stream)	true
-i, --include <PATTERN>	Include logs matching advanced pattern (&&, ||, !, quotes, regex)	-
-e, --exclude <PATTERN>	Exclude logs matching advanced pattern	-
-T, --timestamps	Show timestamps in logs	-
-o, --output <FORMAT>	Output format (text, json, raw)	text
-w, --output-file <FILE>	Write logs to file (use with --ui for both file and UI)	-
-r, --resource <KIND/NAME>	Select pods by resource owner (e.g., deploy/foo, sts/bar)	-
--exec-template <NAME>	Execute predefined template (jfr, heap-dump, thread-dump)	-
--template-args <ARGS>...	Arguments to pass to the template	-
--list-templates	List available templates	-
--template-output <DIR>	Directory to save template outputs	-
--since <DURATION>	Show logs since duration (e.g., 5s, 2m, 3h)	-
--threads <N>	Threads for log filtering	2x CPU cores
--ui	Enable interactive UI mode with dynamic filtering	-
--no-ui	Disable UI and force CLI output	-
--dev	Enable development mode (internal logs)	-
--buffer-size <N>	Number of log entries to keep in memory	20000
-v, --verbosity <LEVEL>	Verbosity for internal debug output	0
--script-in <PATH>	Run a script in each selected pod and collect output	-
--script-outdir <DIR>	Directory to save script outputs (overrides config)	-
--his [QUERY]	Show command history or search saved commands using TF-IDF	-
--web	Send filtered logs to web endpoint via HTTP (configure with wake setconfig web.*)	-
--guide	Open the interactive HTML guide in your browser	-
-h, --help	Print this help	-
-V, --version	Print version	-

For an interactive experience, launch the Terminal UI (TUI) mode. This allows for real-time filtering, searching, and navigation within your terminal.

wake --ui

Use arrow keys to scroll, f to filter, and q to quit.

🔍 Show TUI Screenshot

Wake can send filtered logs to a web endpoint for viewing. This is great for sharing and collaboration. It integrates with OpenObserve.

Before you start:

mkdir -p data
chmod +x data

1. Start OpenObserve with Docker:

docker run -d \
  --name openobserve \
  -v $PWD/data:/data \
  -p 5080:5080 \
  -e ZO_ROOT_USER_EMAIL="root@example.com" \
  -e ZO_ROOT_USER_PASSWORD="Complexpass#123" \
  -e ZO_COMPACT_DATA_RETENTION_DAYS=3 \
  -e ZO_ORG_DATA_QUOTA=10737418240 \
  -e ZO_STREAM_DATA_QUOTA=2147483648 \
  public.ecr.aws/zinclabs/openobserve:latest

2. Configure Wake to use the web endpoint:

wake setconfig web.endpoint "http://localhost:5080"
wake setconfig web.user "root@example.com"
wake setconfig web.password "Complexpass#123"

Note: The default web endpoint is http://localhost:5080, user email is root@example.com, and password is Complexpass#123.
If you change the endpoint, user, or password, make sure to update the configuration using the above wake setconfig commands.

3. Run Wake in web mode:

# Send all logs from the "my-app" pod containing "error"
wake "my-app" -i "error" --web

Access the OpenObserve UI at http://localhost:5080. The stream name will be auto-generated daily (e.g., logs_wake_{namespace}_YYYY_MM_DD).

🔍 Show Web View Screenshot

For detailed usage of OpenObserve's search and "Search Around" features, see the official user guide:

OpenObserve — Search Around: How to use

Wake supports advanced filtering to help you find exactly what you need.

# Include logs that contain "error" OR "warn"
wake "my-app" -i '"error" || "warn"'

# Exclude logs that contain "debug"
wake "my-app" -e "debug"

# Complex query: (error OR warn)
wake "my-app" -i '"error" || "warn"'

Wake can monitor resource usage of your pods, providing real-time insights into CPU and memory consumption.

wake --monitor

Configure monitoring options in your wake.yaml or via command-line flags.

Templates allow you to execute predefined commands inside your pods. This is useful for diagnostics like thread dumps or heap dumps.

# List available templates
wake --list-templates

# Execute the 'thread-dump' template on 'my-app'
wake "my-app" --exec-template thread-dump

# Save the output to a specific directory
wake "my-app" --exec-template heap-dump --template-output /tmp/heap-dumps

Execute custom scripts inside each selected pod and collect the output.

# Run a script to check disk usage
wake "my-app" --script-in ./scripts/check_disk.sh --script-outdir /tmp/disk_usage

Customize Wake's behavior through configuration commands.

# Open an interactive UI to edit all settings
wake setconfig

# Show all current configuration
wake getconfig

# Get a specific configuration key
wake getconfig web.endpoint

🔍 Show Configuration Screenshot

This image shows how the settings / configuration screen looks.

Wake saves your command history and allows you to search it using TF-IDF for intelligent retrieval.

# Search for commands related to "error logs"
wake --his "error logs"

# Show all command history
wake --his

Example: wake --his jfr

Install or update Wake on macOS using Homebrew, or run from source using Cargo.

Versioning

Wake follows semantic versioning: MAJOR.MINOR.PATCH.

• MAJOR — incompatible API or behaviour changes (breaking changes).
• MINOR — new features, backwards-compatible.
• PATCH — bug fixes and small improvements, backwards-compatible.

Examples: 1.2.0 → new features since 1.1.x; 2.0.0 → breaking changes from 1.x.

Check the Wake version locally:

wake --version
# or
wake -V

1. Install

Install via Homebrew (macOS):

brew install samba-rgb/wake/wake

Or build and run from source (developer / latest):

# Clone the repository
git clone https://github.com/samba-rgb/wake.git
cd wake

# Build and run (debug)
cargo run

# Or build release and run
cargo build --release
./target/release/wake --help

Source and contributions: https://github.com/samba-rgb/wake

2. Update

Update the Homebrew package on macOS:

brew upgrade samba-rgb/wake/wake

Or, if you installed from source, update and re-run:

cd wake
git pull origin main   # or the branch you track
cargo run              # run latest changes
# Or rebuild release
cargo build --release
./target/release/wake --help