tailspin

tspin is a command line tool designed to highlight log files. You can use it to view files in a pager (defaulting to less), follow files, or run commands and view their output with syntax highlighting.

Common usage patterns include:

• Reading a file and viewing it in a pager.
• Piping data into tspin to print to stdout.
• Running a command and viewing the output in a pager.
• Following a file (tailing).

The tspin binary can be used to view log files, pipe data into it, or run commands and view their output in a pager.

Basic Usage

• Read a file in less: tspin application.log
• Pipe input to stdout: echo "hello null" | tspin
• Follow live logs from stdin: kubectl logs [pod_name] --follow | tspin
• Run a command and view output in less: tspin --exec='kubectl logs -f pod_name'

# Read from file and view in `less`
tspin application.log

# Pipe something into `tspin` and print to stdout
echo "hello null" | tspin

# Read from stdin and print to stdout
kubectl logs [pod_name] --follow | tspin

# Run the provided command and view the output in `less`
tspin --exec='kubectl logs -f pod_name'

To create a custom theme, run tspin with the --generate-default-theme flag. This prints the default theme.toml content to stdout. You can then redirect this output to your config file to override specific styles.

Example:

You can install tailspin using various package managers or by building from source.

Package Managers

# Homebrew
brew install tailspin

# Cargo
cargo install tailspin

# Archlinux
pacman -S tailspin

# Nix
nix-shell -p tailspin

# NetBSD
pkgin install tailspin

# FreeBSD
pkg install tailspin

# Windows (Scoop)
scoop install tailspin

From Source

cargo install --path .

Note: When building from source, ensure you are using the latest version of less. The binary will be placed in ~/.cargo/bin; ensure this directory is in your PATH.

Tailspin uses less as its default pager.

Navigation

• j/k: Scroll one line up/down
• d/u: Scroll one half-page up/down
• g/G: Go to the top/bottom of the file
• /: Search (followed by query)
• n/N: Next/Previous search match

Follow Mode

• -f or --follow: Scrolls to the bottom and prints new lines as they arrive.
• Shift + F: Resume following from within less.
• Ctrl + C: Stop following but keep the file open for review.

Filtering

• &[pattern]: Show only lines matching the pattern (e.g., &ERROR).
• &(pattern1|pattern2): Show lines matching multiple patterns using regex (e.g., &(ERROR|WARN)).
• &: Clear the filter.

Custom Pager

Set TAILSPIN_PAGER to override the default. The command must include the string [FILE] to be replaced by the file path.

TAILSPIN_PAGER="ov -f [FILE]" tspin example-logs/example1

Tailspin is a CLI tool designed to read input (from files, stdin, or commands) and output highlighted text to either stdout or a pager (like less).

Based on the implementation, the tool supports several modes of operation:

• Read from file: View file contents with syntax highlighting in a pager.
• Pipe input: Pipe data into tspin to print highlighted output to stdout.
• Read from stdin: Read directly from standard input.
• Run command: Execute a command and view its output in a pager.

To use the tool, you typically invoke the binary with your desired source and target. The tool handles the orchestration of reading, highlighting via Highlighter, and presenting the output.

Specify a custom theme file using the --theme flag or the TAILSPIN_THEME environment variable.

Default Search Paths:

• Linux/macOS: $XDG_CONFIG_HOME/tailspin/theme.toml or ~/.config/tailspin/theme.toml
• Windows: %APPDATA%\tailspin\theme.toml

Tailspin applies keyword highlighting using a 'last-wins' precedence model. When multiple definitions for the same word exist, the one defined latest in the following hierarchy takes precedence:

1. CLI Flags: Keywords provided via the command line (e.g., using --highlight).
2. Theme Keywords: Keywords defined in your configuration theme under the [[keywords]] section.
3. Builtin Keywords: Default keywords provided by Tailspin (if enabled).

If a word is redefined in a higher-precedence category, the style from that category is used. However, unrelated words within the same configuration group are preserved.

You can generate a complete theme.toml file containing all default styles by running the following command. This is useful for creating a base configuration that you can then customize.

To use the generated theme, copy the output to ~/.config/tailspin/theme.toml.

Note:

• Keyword ([[keywords]]) and regex ([[regexes]]) highlights are additive; the built-in keywords are compiled into tspin and your custom lists will be added to them.
• If you copy the file but leave it unchanged, it has no effect. To customize, edit the specific styles you want to override and delete the rest.

tspin --generate-default-theme

To use tailspin as a library and avoid pulling in CLI-specific dependencies like clap and rayon, disable default features in your Cargo.toml.

[dependencies]
tailspin = { version = "7.0", default-features = false }