CLI

A Rust CLI for querying logs from the terminal. Supports LogchefQL, raw SQL, syntax highlighting (via tailspin), multi-context management (dev/staging/prod), and OIDC PKCE authentication.

Quick Start

# 1. Build the CLI
cd logchef/cli && cargo build --release

# 2. Add to PATH (or copy to /usr/local/bin)
export PATH="$PATH:$(pwd)/target/release"

# 3. Authenticate (auto-creates context from hostname)
logchef auth --server https://logs.example.com

# 4. Rename context to something friendly
logchef config rename logs.example.com prod

# 5. Set defaults so you don't need --team/--source every time
logchef config set team "my-team"
logchef config set source "nginx-logs"

# 6. Query logs
logchef query 'level="error"' --since 1h

Tip: Discover teams and sources with:

logchef teams
logchef sources --team "production"
logchef schema --team "production" --source "nginx-logs"

Copy CLI Command from Web UI

In the LogChef web UI, click the terminal icon (next to the share button) in the explore view to copy the equivalent CLI command for your current query. This is a quick way to transition from the web UI to the terminal.

Installation

Pre-built Binaries (Recommended)

Download the latest CLI release for your platform from GitHub Releases.

Platform	File
Linux x86_64	logchef-cli_<version>_linux-x86_64-musl.tar.gz
Linux ARM64	logchef-cli_<version>_linux-aarch64-musl.tar.gz
macOS Apple Silicon	logchef-cli_<version>_macos-aarch64.tar.gz
macOS Intel	logchef-cli_<version>_macos-x86_64.tar.gz
Windows x86_64	logchef-cli_<version>_windows-x86_64.zip

# Example: Download and install (replace VERSION with actual version)
VERSION="0.1.6"

# Linux x86_64
curl -LO "https://github.com/mr-karan/logchef/releases/download/cli-v${VERSION}/logchef-cli_${VERSION}_linux-x86_64-musl.tar.gz"
tar xzf logchef-cli_${VERSION}_linux-x86_64-musl.tar.gz
sudo mv logchef /usr/local/bin/

# macOS Apple Silicon
curl -LO "https://github.com/mr-karan/logchef/releases/download/cli-v${VERSION}/logchef-cli_${VERSION}_macos-aarch64.tar.gz"
tar xzf logchef-cli_${VERSION}_macos-aarch64.tar.gz
sudo mv logchef /usr/local/bin/

Check Latest Version

Visit the CLI releases page to find the latest version number.

From Source

If you prefer to build from source (requires Rust):

# Clone the repository
git clone https://github.com/mr-karan/logchef.git
cd logchef/cli

# Build the release binary
cargo build --release

# The binary is at cli/target/release/logchef
# Copy to your PATH:
sudo cp target/release/logchef /usr/local/bin/

Using Just

If you have just installed:

# Build release binary
just build-cli

# Build debug binary (faster compilation for testing)
just build-cli-debug

# Install to ~/.cargo/bin (must be in PATH)
just install-cli

Verify Installation

logchef --version
logchef --help

Authentication

The CLI supports two authentication methods: browser-based OIDC and API tokens.

Server Prerequisite (OIDC)

To use browser-based auth, configure a public OIDC client for the CLI and set it in the server config:

[oidc]
cli_client_id = "logchef-cli"

Your OIDC provider must allow loopback redirects for the CLI: http://127.0.0.1:19876/callback through http://127.0.0.1:19878/callback.

Browser-Based Login (OIDC)

For interactive use, authenticate via your browser:

logchef auth

This opens your browser to complete the OIDC login flow. The token is automatically saved to your config file.

# Check authentication status (hits the server)
logchef auth --status

# Print the active context, server URL, and token source (offline — no API call)
logchef auth current

# Log out (clear stored token)
logchef auth --logout

auth current is the offline counterpart to auth --status and whoami. It tells you which server + token a subsequent command will use, without making a network call:

context: prod
server:  https://logs.example.com
token:   set (from config, expires 2026-06-03T07:00:00Z)

When the token comes from --token / LOGCHEF_AUTH_TOKEN, the line reports the source but omits an expiry (the CLI doesn’t validate or parse externally-supplied tokens). Useful for CI / bot debugging when an API call fails and you want to verify the credential is actually picked up before troubleshooting further.

API Token Authentication

For scripts and automation, use an API token directly:

# Set token via environment variable
export LOGCHEF_AUTH_TOKEN="logchef_1_abc123..."
logchef query ""

# Or pass token as argument
logchef --token "logchef_1_abc123..." query ""

# Or save to config file
logchef config set auth.token "logchef_1_abc123..."

Generate API tokens from the LogChef web UI under your profile settings.

Command Reference

Query Logs

The query command allows you to execute LogChefQL queries directly from your terminal.

logchef query 'level="error" and service="api"' --since 1h

Options

Option	Shorthand	Description	Default
--team	-t	Team name (or ID)	(from config)
--source	-S	Source name, database.table_name, or ID	(from config)
--since	-s	Time range (e.g., “15m”, “1h”, “24h”)	“15m”
--from		Absolute start time (ISO 8601)
--to		Absolute end time (ISO 8601)
--limit	-l	Maximum number of results	100
--output		Output format (text, json, jsonl, json-flat, table, msg)	text
--no-highlight		Disable syntax highlighting (auto-disabled when piped)	false
--no-timestamp		Hide timestamp from text output	false
--show-sql, --explain		Trace the server-generated SQL on stderr (continues executing)	false
--dry-run		Print the server-generated SQL to stdout and exit	false

Interactive Mode

When you run logchef query without specifying team, source, or query, and you’re in a terminal, the CLI enters interactive mode:

# Launch interactive mode
logchef query

# Prompts:
# ? Select team: [production, staging, dev]
# ? Select source: [nginx-logs, app-logs, api-logs]
# ? LogChefQL query: level="error"

This is useful for quick exploration without remembering exact team/source names.

Query Examples

# Get all logs from the last 15 minutes
logchef query "" --team "production" --source "nginx-logs"

# Use database.table_name format (copy from UI)
logchef query "" --team "production" --source "logs.app"

# Filter by field value
logchef query 'status=500' --team "production" --source "nginx-logs"

# Multiple conditions (AND)
logchef query 'method="POST" and status=403' --team "production" --source "nginx-logs"

# Search within a time range
logchef query 'level="error"' --since 1h --limit 50

# Print only the message column
logchef query 'level="error"' --output msg --limit 5

# Hoist JSON-shaped msg fields to top-level JSON rows
logchef query 'level="error"' --output json-flat --limit 5

# Hide timestamp from output
logchef query 'level="error"' --no-timestamp

# Output as JSON (returns object with logs, stats, columns)
logchef query 'status=500' --output json | jq '.logs[] | .host'

# Output as JSON Lines (one JSON object per line, great for jq)
logchef query "" --output jsonl | jq '.msg'

# JSON output is jq-friendly - stats are included in the object
logchef query "" --output json | jq '{count: .count, time_ms: .stats.execution_time_ms}'

# Trace the generated SQL on stderr while still running
logchef query 'method="GET"' --show-sql        # or: --explain

# Print the generated SQL to stdout and exit (no results returned)
logchef query 'method="GET"' --dry-run

# Use absolute time range
logchef query "" --from "2026-01-14T00:00:00Z" --to "2026-01-14T12:00:00Z"

Raw SQL Queries

The sql command lets you execute raw ClickHouse SQL directly. Unlike query, you have full control over the SQL—including time filters, aggregations, and joins.

logchef sql "SELECT * FROM logs.app WHERE level='error' LIMIT 10"

Options

Option	Shorthand	Description	Default
--team	-t	Team name (or ID)	(from config)
--source	-S	Source name, database.table_name, or ID	(from config)
--since	-s	Apply a relative time range (e.g., “15m”, “1h”, “24h”)
--from		Apply an absolute start time (YYYY-MM-DD HH:MM:SS)
--to		Apply an absolute end time (YYYY-MM-DD HH:MM:SS)
--timeout		Query timeout in seconds	30
--output		Output format (text, json, jsonl, json-flat, table, csv, msg)	text
--no-highlight		Disable syntax highlighting (auto-disabled when piped)	false
--no-timestamp		Hide timestamp from text output	false
--show-sql, --explain		Trace the resolved SQL on stderr (continues executing)	false
--dry-run		Print the resolved SQL to stdout and exit without running it	false

Interactive Mode

Similar to query, the sql command supports interactive mode:

# Launch interactive mode
logchef sql

# Prompts:
# ? Select team: [production, staging, dev]
# ? Select source: [nginx-logs, app-logs, api-logs]
# ? SQL query: SELECT * FROM logs.app LIMIT 10

SQL Examples

# Simple query with time filter
logchef sql "SELECT * FROM logs.app WHERE _timestamp > now() - INTERVAL 1 HOUR LIMIT 100"

# Aggregation query
logchef sql "SELECT level, count() as cnt FROM logs.app WHERE _timestamp > now() - INTERVAL 1 DAY GROUP BY level"

# Let the CLI add the source timestamp range
logchef sql "SELECT level, count() AS count FROM logs.app GROUP BY level" --since 1h

# Place the time expressions explicitly
logchef sql "SELECT * FROM logs.app WHERE _timestamp BETWEEN __START__ AND __END__" --since 1h

# Read SQL from stdin (useful for complex queries)
cat query.sql | logchef sql -

# Or use heredoc
logchef sql - <<'EOF'
SELECT
    toStartOfHour(_timestamp) as hour,
    count() as requests,
    countIf(status >= 500) as errors
FROM logs.nginx
WHERE _timestamp > now() - INTERVAL 24 HOUR
GROUP BY hour
ORDER BY hour
EOF

# Output as JSON
logchef sql "SELECT * FROM logs.app LIMIT 5" --output json

# Print only msg, or the first selected column when msg is absent
logchef sql "SELECT msg FROM logs.app LIMIT 5" --output msg

# Trace the resolved SQL on stderr while still running the query
logchef sql "SELECT count() FROM logs.app WHERE level='error'" --since 1h --explain

# Print the resolved SQL and exit (useful for piping to another tool)
logchef sql "SELECT count() FROM logs.app WHERE level='error'" --since 1h --dry-run

# Pipe to jq for processing
logchef sql "SELECT host, count() as cnt FROM logs.app GROUP BY host" --output jsonl | jq -s 'sort_by(.cnt) | reverse'

When to use sql vs query

• Use query (LogChefQL) for quick filtering with convenient time flags (--since 1h)
• Use sql when you need aggregations, joins, CTEs, or full SQL control

Auto-injected time predicate

--since / --from / --to work on the top-level SELECT. The CLI walks the SQL skipping string literals, quoted identifiers, and parenthesized subqueries, then injects the predicate before the first top-level GROUP BY / ORDER BY / LIMIT / HAVING / SETTINGS / FORMAT. For CTEs (WITH ... AS (...)) or any case where you want full control, use the __START__ / __END__ placeholders explicitly.

Source Discovery

The find command searches accessible sources for a service, job, host, or message pattern and prints the sources with recent matches.

logchef find payments-api
logchef find payments-api --team production --since 6h

Find Options

Option	Shorthand	Description	Default
--team	-t	Restrict discovery to one team	All accessible teams
--source	-S	Restrict discovery to one source	All sources
--since	-s	Lookback window	24h
--column		Candidate column to search; repeatable	Common service/job/host/message columns
--limit		Maximum matching sources to print	10
--timeout		Per-source query timeout in seconds	30
--no-samples		Skip the per-column sample fetch	false
--output		Output format (text, json, jsonl)	text

For each matched source, find fires a small follow-up query per matching column to surface sample values:

team=8 source=11 (logs.app)  matches=1401245 in 30m columns=job_name,msg
  ↳ job_name: "payments-api" (1400128), "payments-api-uat" (1117)
  ↳ msg: "payments-api handled request 0a3f9b…" (sample)

Label-shaped columns (service, host, job_name, …) get the top 3 values with counts; free-form text columns (msg, message, body) get a single truncated sample row. Pass --no-samples to suppress and get just the summary line. In JSON / JSONL output, samples are included as a samples: [{column, values: [{value, count?}]}] field.

Sources that fail to inspect (permissions, schema fetch, or query errors) are silently skipped. The text output reports the skip count on stderr; pass the global --debug flag to see per-source diagnostics. If a source consistently times out (e.g. very wide table over a long lookback), raise --timeout or narrow with --since / --column.

Tail

The tail command follows matching LogChefQL results by polling for new rows and streaming them until Ctrl-C or --max-lines is reached.

logchef tail 'service="payments-api" and msg~"error"' -t production -S app-logs
logchef tail 'level="error"' --output jsonl --max-lines 20

Tail Options

Option	Shorthand	Description	Default
--team	-t	Team name or ID	(from env/config)
--source	-S	Source name, database.table_name, or ID	(from env/config)
--since	-s	Initial lookback window	30s
--interval		Poll interval in seconds	2
--limit		Maximum rows fetched per poll	100
--max-lines		Stop after printing this many rows
--output		Output format (text, jsonl, msg)	text
--no-highlight		Disable syntax highlighting (auto-disabled when piped)	false

If a single poll returns at --limit, tail prints a one-shot stderr warning: between polls, more rows may have arrived than fit in one fetch. Raise --limit or shrink --interval to keep up.

Highlighting is auto-disabled when stdout is not a TTY, so logchef tail '...' | jq and ... > log.txt produce clean output without --no-highlight. The flag still works as an explicit override.

Example Output

When running a query, you’ll see highlighted output with colors:

2026-01-14T07:16:06.149Z host=172.100.86.236 method=PATCH status=410 bytes=45112
2026-01-14T07:16:06.049Z host=156.89.90.123 method=PATCH status=200 bytes=42092
2026-01-14T07:16:05.949Z host=217.33.68.177 method=POST status=403 bytes=10709

The highlighting includes:

• Timestamps in magenta
• IP addresses in cyan
• URLs with protocol highlighting
• Key=value pairs with dimmed keys
• Numbers in cyan
• Log levels color-coded (ERROR=red, WARN=yellow, INFO=green, DEBUG=blue)

Saved Queries

The saved-queries command lists and runs saved queries from the LogChef web UI. You can pass a saved-query ID, exact name, or an explorer URL copied from the browser.

# List all saved queries visible to your account
logchef saved-queries

# Run by numeric ID
logchef saved-queries 14

# Run by pasted explorer URL
logchef saved-queries "https://logs.example.com/logs/explore?team=8&source=11&id=14"

Options

Option	Shorthand	Description	Default
--team	-t	Team name or ID	Query’s resolved team
--source	-S	Source name, database.table_name, or ID	Query’s source
--limit	-l	Override maximum number of results	From saved query
--var	-V	Set variable value (format: name=value)
--show-sql		Print the resolved query without running it	false
--output		Output format (text, json, jsonl, json-flat, table, msg)	text
--no-highlight		Disable syntax highlighting	false
--no-timestamp		Hide timestamp from text output	false

Saved Query Examples

# List as JSON
logchef saved-queries --output json | jq '.[] | {id, name, source_name}'

# Run by name
logchef saved-queries "Error Dashboard"

# Substitute variables from the saved query envelope
logchef saved-queries 14 --var service=api --var level=error

# Print only message text
logchef saved-queries 14 --output msg

# Dry-run the stored query text
logchef saved-queries 14 --show-sql

Collections

The collections command lets you list and run saved collections (saved queries) from the LogChef web UI.

# List all collections for a source
logchef collections --team "production" --source "nginx-logs"

# Run a collection by name
logchef collections "Error Dashboard" --team "production" --source "nginx-logs"

Options

Option	Shorthand	Description	Default
--team	-t	Team name (or ID)	(from config)
--source	-S	Source name, database.table_name, or ID	(from config)
--since	-s	Override time range (e.g., “15m”, “1h”, “24h”)	(from collection)
--from		Override absolute start time (ISO 8601)
--to		Override absolute end time (ISO 8601)
--limit	-l	Override maximum number of results	(from collection)
--var		Set variable value (format: name=value)
--output		Output format (text, json, jsonl, json-flat, table, msg)	text
--no-highlight		Disable syntax highlighting	false
--no-timestamp		Hide timestamp from text output	false
--show-sql		Display the generated SQL query	false

Interactive Mode

When run without arguments, enters interactive mode to select team, source, and collection:

# Launch interactive mode
logchef collections

# Prompts:
# ? Select team: [production, staging, dev]
# ? Select source: [nginx-logs, app-logs, api-logs]
# ? Select collection: [Error Dashboard, Slow Requests, Daily Summary]

Collection Examples

# List all collections
logchef collections -t "production" -S "nginx-logs"
#   ID   NAME                           TYPE         DESCRIPTION
#   1    Error Dashboard                logchefql    Track 5xx errors
#   2    Slow Requests                  logchefql    Requests > 1s

# Run a collection with default settings
logchef collections "Error Dashboard" -t "production" -S "nginx-logs"

# Override time range
logchef collections "Error Dashboard" -t 1 -S 1 --since 1h

# Set variables defined in the collection
logchef collections "Service Logs" --var service=api --var level=error

# Output as JSON
logchef collections "Error Dashboard" --output json | jq '.count'

Collections vs Query

Collections are saved queries with predefined settings (time ranges, limits, variables). Use them for repeatable queries you’ve set up in the web UI. Use query for ad-hoc exploration.

Teams

List teams available to your account:

logchef teams

Options

Option	Description	Default
--output	Output format (text, json, jsonl, table)	text

Whoami

Show the authenticated user and accessible teams:

logchef whoami
logchef whoami --output json

Sources

List sources for a team:

logchef sources --team "production"

Options

Option	Shorthand	Description	Default
--team	-t	Team name (or ID)	(from config)
--output		Output format (text, json, jsonl, table)	text

Schema

Show the schema for a source. If the ClickHouse table has column comments, LogChef exposes them as description in JSON output and shows them in the text table.

logchef schema --team "production" --source "nginx-logs"

Options

Option	Shorthand	Description	Default
--team	-t	Team name (or ID)	(from config)
--source	-S	Source name, database.table_name, or ID	(from config)
--output		Output format (text, json, jsonl, table)	text

Configuration

Manage your CLI settings using the config command.

# List all contexts
logchef config list

# Switch to a different context
logchef config use prod

# Show current context configuration
logchef config show

# Set configuration values for current context
logchef config set team 2
logchef config set source 2
logchef config set limit 50
logchef config set since "1h"

# Rename a context
logchef config rename logs.example.com prod

# Delete a context
logchef config delete old-server

Multi-Context Workflow

The CLI supports managing multiple LogChef instances (dev/staging/prod):

# Authenticate with prod (context auto-created from hostname)
logchef auth --server https://logs.company.com
logchef config rename logs.company.com prod

# Authenticate with dev
logchef auth --server http://localhost:8125
logchef config rename localhost dev

# List contexts
logchef config list
#     CONTEXT  SERVER                        AUTH
#   * prod     https://logs.company.com      yes
#     dev      http://localhost:8125         yes

# Switch contexts
logchef config use dev
logchef query 'level="debug"'

# One-off query to different context
logchef --context prod query 'level="error"'

Recommended Setup

After authenticating, set your defaults to avoid typing --team and --source every time:

# Set defaults using team and source names
logchef config set team "my-team"
logchef config set source "nginx-logs"

# Now you can just run:
logchef query 'level="error"'

Source Resolution

The --source flag accepts multiple formats:

• Friendly name: "Application Logs" (case-insensitive)
• Table reference: logs.app (as shown in UI, case-insensitive)
• Numeric ID: 11

Lookups are cached locally (~/.cache/logchef/) for 10 minutes.

Configuration File

The configuration is stored at ~/.config/logchef/logchef.json:

{
  "current_context": "prod",
  "contexts": {
    "prod": {
      "server_url": "https://logs.example.com",
      "timeout_secs": 30,
      "token": "logchef_1_...",
      "token_expires_at": "2026-02-14T00:00:00Z",
      "defaults": {
        "team": "production",
        "source": "nginx-logs",
        "limit": 100,
        "since": "15m"
      }
    },
    "dev": {
      "server_url": "http://localhost:8125",
      "timeout_secs": 30,
      "token": "logchef_1_...",
      "defaults": {}
    }
  },
  "highlights": {
    "custom_keywords": ["MYAPP", "CRITICAL"],
    "disable_builtin": false,
    "disabled_groups": [],
    "custom_regexes": [
      {
        "pattern": "trace_id=[a-f0-9]+",
        "color": "cyan",
        "bold": false,
        "italic": false
      }
    ]
  }
}

Configuration Options

Section	Key	Description
current_context	Active context	Name of the context to use by default
contexts.<name>.server_url	Server URL	LogChef server address for this context
contexts.<name>.timeout_secs	Timeout	HTTP request timeout in seconds
contexts.<name>.defaults.team	Default team	Team name (or ID) to use when --team is omitted
contexts.<name>.defaults.source	Default source	Source name (or ID) to use when --source is omitted
contexts.<name>.defaults.limit	Default limit	Number of results when --limit is omitted
contexts.<name>.defaults.since	Default time range	Time range when --since is omitted
highlights.custom_keywords	Custom keywords	Words to highlight in magenta
highlights.disable_builtin	Disable defaults	Turn off built-in log level highlighting
highlights.disabled_groups	Disabled groups	List of highlighter groups to disable
highlights.custom_regexes	Custom patterns	Regex patterns with custom colors

Syntax Highlighting

LogChef CLI provides automatic syntax highlighting for common log patterns, powered by tailspin.

Built-in Highlighting

Category	What’s Highlighted	Colors
Log Levels	ERROR, FATAL, CRITICAL	Red (bold)
	WARN, WARNING	Yellow
	INFO	Green
	DEBUG, TRACE	Blue
HTTP Methods	GET	Green (bold)
	POST	Yellow (bold)
	PUT, PATCH	Magenta (bold)
	DELETE	Red (bold)
Identifiers	IPs, UUIDs, URLs	Cyan/Blue
Temporal	Dates, timestamps	Magenta
Data	Numbers, key=value pairs	Cyan
Booleans	true, false, null	Cyan

Ad-hoc Highlighting

Highlight specific words on-the-fly without changing your config:

# Highlight words in specific colors
logchef query "" --highlight red:ERROR,FAIL --highlight green:SUCCESS,OK

# Available colors: red, green, yellow, blue, magenta, cyan, white, black
# Also: bright_red, bright_green, bright_yellow, etc.

Disable Highlighters

Turn off specific highlighting groups for cleaner output:

# Disable date/time and number highlighting
logchef query "" --disable-highlight dates --disable-highlight numbers

# Available groups: dates, numbers, uuids, ips, urls, paths,
#                   pointers, keyvalue, quotes, json, keywords

Custom Regex Patterns

Add custom regex patterns in your config file:

{
  "highlights": {
    "custom_regexes": [
      {
        "pattern": "user_id=(\\d+)",
        "color": "cyan",
        "bold": true
      },
      {
        "pattern": "request_id=[a-f0-9-]+",
        "color": "magenta"
      }
    ]
  }
}

Disable All Highlighting

The CLI auto-disables ANSI highlighting when stdout is not a TTY, so piping or redirecting just works:

logchef query "" > logs.txt
logchef tail '...' --output jsonl | jq -r .msg

Use --no-highlight to opt out explicitly even on an interactive terminal:

logchef query "" --no-highlight | grep "ERROR"

Output Formats

JSON Format (--output json)

Returns a single JSON object containing logs, stats, and metadata:

{
  "logs": [
    { "_timestamp": "2026-01-20T10:30:00Z", "level": "error", "msg": "..." },
    { "_timestamp": "2026-01-20T10:29:59Z", "level": "info", "msg": "..." }
  ],
  "count": 2,
  "stats": {
    "execution_time_ms": 45,
    "rows_read": 2,
    "bytes_read": 1024
  },
  "query_id": "abc123-...",
  "generated_sql": "SELECT * FROM ...",
  "columns": [
    { "name": "_timestamp", "type": "DateTime64(3)" },
    { "name": "level", "type": "String" }
  ]
}

JSON Lines Format (--output jsonl)

Each log entry is output as a separate JSON object on its own line:

{"_timestamp":"2026-01-20T10:30:00Z","level":"error","msg":"Connection failed"}
{"_timestamp":"2026-01-20T10:29:59Z","level":"info","msg":"Request completed"}

Smart Output Detection

The CLI automatically detects if output is going to a terminal (TTY) or being piped:

• Terminal: Shows stats summary (3 logs | 45ms | 3 rows read)
• Piped: Suppresses stats for clean output to grep, jq, etc.

# Stats shown (terminal)
logchef query ""
# Output: [logs...]
# 3 logs | 45ms | 3 rows read

# Stats suppressed (piped)
logchef query "" | grep "error"
# Output: [matching lines only, no stats]

Global Options

The following options can be used with any command:

Option	Environment Variable	Description
--context / -c	LOGCHEF_CONTEXT	Use a specific context
--server	LOGCHEF_SERVER_URL	Override server URL (ephemeral)
--token	LOGCHEF_AUTH_TOKEN	Override API token
	LOGCHEF_DEFAULT_TEAM	Default team when --team is omitted
	LOGCHEF_DEFAULT_SOURCE	Default source when --source is omitted
--debug / -d		Enable detailed debug output

Environment Variables

For CI/CD pipelines and automation, you can configure the CLI entirely via environment variables:

# Option 1: Use a saved context
export LOGCHEF_CONTEXT="prod"
logchef query 'level="error"' --team "production" --source "app-logs"

# Option 2: Ephemeral mode (no saved context needed)
export LOGCHEF_SERVER_URL="https://logs.example.com"
export LOGCHEF_AUTH_TOKEN="logchef_1_abc123..."
logchef query 'level="error"' --team "production" --source "app-logs"

# Optional defaults for stateless automation
export LOGCHEF_DEFAULT_TEAM="production"
export LOGCHEF_DEFAULT_SOURCE="app-logs"
logchef query 'level="error"'

Scripting Examples

Export logs to file

logchef query 'status=500' --output jsonl > errors.jsonl

Count errors with jq

logchef query 'level="error"' --output json | jq '.count'

Extract specific fields with jq

# Get all unique hosts from JSON output
logchef query 'status=500' --output json | jq -r '.logs[].host' | sort -u

# Get all unique hosts from JSONL output
logchef query 'status=500' --output jsonl | jq -r '.host' | sort -u

# Pretty print messages
logchef query 'level="error"' --output jsonl | jq '.msg'

# Get query stats
logchef query "" --output json | jq '.stats'

Pipe to grep for filtering

logchef query "" --no-highlight | grep -i "database"

Clean output without timestamps

logchef query 'level="error"' --no-timestamp --no-highlight > errors.txt

Loop through multiple sources

for source in "nginx-logs" "app-logs" "api-logs"; do
  echo "=== Source: $source ==="
  logchef query 'level="error"' --source "$source" --limit 5
done