Timberlogs CLI

Official CLI for Timberlogs — query logs, inspect flows, and view stats from your terminal.

Quick Start

npm install -g timberlogs-cli
timberlogs login
timberlogs logs --level error --from 1h

Commands

Authentication

timberlogs login                    # Authenticate via browser (OAuth device flow)
timberlogs logout                   # Remove stored session
timberlogs whoami                   # Show current auth status

Logs

timberlogs logs                          # Last hour of logs
timberlogs logs --level error --from 24h # Errors from last 24 hours
timberlogs logs --search "payment"       # Full-text search
timberlogs logs --source api-server      # Filter by source
timberlogs logs --flow-id checkout-abc   # Logs for a specific flow

Flag	Description
--level	Filter by level (debug, info, warn, error)
--source	Filter by source name
--env	Filter by environment
--search	Full-text search (uses /v1/logs/search)
--from	Start time (30m, 1h, 24h, 7d, or ISO 8601)
--to	End time
--limit	Max results (default: 50)
--user-id	Filter by user ID
--session-id	Filter by session ID
--flow-id	Filter by flow ID
--dataset	Filter by dataset

Interactive mode: use arrow keys to navigate, Enter to expand a log, q to quit.

Flows

timberlogs flows                        # List all flows
timberlogs flows --from 7d              # Flows from last 7 days
timberlogs flows show <flow-id>         # View flow timeline
timberlogs flows show checkout-abc      # Example

Stats

timberlogs stats                         # Last 24 hours
timberlogs stats --from 7d              # Last 7 days
timberlogs stats --group-by source      # Group by source

Flag	Description
--from	Start time (default: 24h)
--to	End time
--group-by	Grouping: hour, day, source (default: day)
--source	Filter by source
--env	Filter by environment
--dataset	Filter by dataset

Config

timberlogs config list                   # Show current config
timberlogs config reset                  # Delete config file

Global Flags

Flag	Description
--json	Force JSON output
--verbose	Show HTTP request details
--version, -v	Show version
--help, -h	Show help

JSON Mode

All commands support --json for machine-readable output. JSON mode is also auto-detected when stdout is not a TTY (e.g., piped to another command).

# Explicit JSON mode
timberlogs logs --level error --json

# Auto-detected (piped)
timberlogs logs --level error | jq '.logs[].message'

# Use with AI agents
timberlogs logs --search "500 error" --json --from 1h

Environment Variables

Variable	Description
NO_COLOR	Disable color output
TIMBERLOGS_CONFIG_DIR	Custom config directory (default: ~/.config/timberlogs)

Requirements

• Node.js >= 20

License

MIT