Skip to main content

Installation

Requirements: Node.js 20 or later.

REPL

Running timberlogs with no arguments launches an interactive REPL session — a persistent prompt where you can run any command without reinvoking the binary.
Commands work exactly like the CLI — same flags, same output. Commands that produce a table (logs, stats, flows show) take over the full screen with keyboard navigation; press q to return to the prompt. Builtins: help, clear, exit History: Use / to navigate previous commands. History is saved to ~/.config/timberlogs/history.json.

Authentication

The CLI uses OAuth device flow — no API keys needed.
This opens your browser to sign in via Timberlogs. Once approved, the CLI stores a session token locally at ~/.config/timberlogs/config.json.

Querying Logs

Filters

Interactive Mode

The default log view is an interactive table. Use arrow keys to navigate, Enter to expand a log entry, and q to quit.

Output Formats

Flows

Stats

JSON Mode

All commands support --json for machine-readable output. JSON mode is also auto-detected when stdout is piped.

Config

When running inside the REPL, config reset requires --force — interactive confirmation prompts are not supported in the REPL session. Session data is stored at ~/.config/timberlogs/config.json with 600 permissions. Override the directory with the TIMBERLOGS_CONFIG_DIR environment variable.