Skip to main content

​
Installation

npm install -g timberlogs-cli
Requirements: Node.js 20 or later.

​
Authentication

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

​
Querying 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

​
Filters

FlagDescription
--leveldebug, info, warn, or error
--sourceFilter by source name
--envFilter by environment
--searchFull-text search
--fromStart time (30m, 1h, 24h, 7d, or ISO 8601)
--toEnd time
--limitMax results (default: 50)
--user-idFilter by user ID
--session-idFilter by session ID
--flow-idFilter by flow ID
--datasetFilter by dataset

​
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

timberlogs logs --format json     # JSON array
timberlogs logs --format jsonl    # One JSON object per line
timberlogs logs --format csv      # CSV
timberlogs logs --format text     # Plain text
timberlogs logs --format syslog   # Syslog format

​
Flows

timberlogs flows                    # List recent flows
timberlogs flows --from 7d          # Flows from last 7 days
timberlogs flows show <flow-id>     # View flow timeline

​
Stats

timberlogs stats                     # Last 24 hours
timberlogs stats --from 7d           # Last 7 days
timberlogs stats --group-by source   # Group by source
FlagDescription
--fromStart time (default: 24h)
--toEnd time
--group-byhour, day, or source (default: day)
--sourceFilter by source
--envFilter by environment
--datasetFilter by dataset

​
JSON Mode

All commands support --json for machine-readable output. JSON mode is also auto-detected when stdout is piped. 
# Explicit
timberlogs logs --level error --json

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

​
Config

timberlogs config list     # Show current config
timberlogs config reset    # Delete config file
Session data is stored at ~/.config/timberlogs/config.json with 600 permissions. Override the directory with the TIMBERLOGS_CONFIG_DIR environment variable.