> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timberlogs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Query logs, inspect flows, and view stats from your terminal.

## Installation

```bash theme={null}
npm install -g timberlogs-cli
```

**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.

```bash theme={null}
timberlogs
```

```
▲  Timberlogs  v1.0.0    ●  Acme Corp
logs  stats  flows  flows show  whoami  login  logout  config list  help  exit
────────────────────────────────────────────────────────────
❯ logs --level error --from 24h
❯ stats --group-by source
❯ flows show checkout-abc-123
```

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.

```bash theme={null}
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`.

```bash theme={null}
timberlogs whoami    # Check auth status
timberlogs logout    # Remove stored session
```

## Querying Logs

```bash theme={null}
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

| Flag           | Description                                        |
| -------------- | -------------------------------------------------- |
| `--level`      | `debug`, `info`, `warn`, or `error`                |
| `--source`     | Filter by source name                              |
| `--env`        | Filter by environment                              |
| `--search`     | Full-text 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

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

```bash theme={null}
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

```bash theme={null}
timberlogs flows                    # List recent flows
timberlogs flows --from 7d          # Flows from last 7 days
timberlogs flows show <flow-id>     # View flow timeline
```

## Stats

```bash theme={null}
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` | `hour`, `day`, or `source` (default: `day`) |
| `--source`   | Filter by source                            |
| `--env`      | Filter by environment                       |
| `--dataset`  | Filter by dataset                           |

## JSON Mode

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

```bash theme={null}
# Explicit
timberlogs logs --level error --json

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

## Config

```bash theme={null}
timberlogs config list           # Show current config
timberlogs config reset          # Delete config file (prompts for confirmation)
timberlogs config reset --force  # Delete without confirmation
```

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.