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.4"

# 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
logchef auth --status

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

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, table)	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 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.nomad_apps"

# 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

# 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}'

# Show the SQL that will be executed
logchef query 'method="GET"' --show-sql

# 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)
--timeout		Query timeout in seconds	30
--output		Output format (text, json, jsonl, table)	text
--no-highlight		Disable syntax highlighting	false
--no-timestamp		Hide timestamp from text output	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"

# 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

# 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

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)

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, table)	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

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 (columns and types) for a source:

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: "Kite Nomad" (case-insensitive)
• Table reference: logs.nomad_apps (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

For piping to other tools or file output:

logchef query "" --no-highlight > logs.txt
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
--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"

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