Lakerunner CLI
The Lakerunner CLI is an intuitive command-line tool to query your S3 logs. It provides fast, flexible access to your observability data without requiring a web interface.
Installation
Grab the Lakerunner CLI from the latest release . Under Assets, choose the appropriate file for your platform:
| Platform | Asset |
|---|---|
| macOS (Apple Silicon) | lakerunner-cli_Darwin_arm64.tar.gz |
| macOS (Intel) | lakerunner-cli_Darwin_x86_64.tar.gz |
| Linux (x86_64) | lakerunner-cli_Linux_x86_64.tar.gz |
| Linux (arm64) | lakerunner-cli_Linux_arm64.tar.gz |
| Windows (x86_64) | lakerunner-cli_Windows_x86_64.zip |
Unpack the archive, then move the lakerunner-cli binary to a location on your PATH.
macOS / Linux:
tar -xzf lakerunner-cli_Darwin_arm64.tar.gz
sudo mv lakerunner-cli /usr/local/bin/
lakerunner-cli --helpWindows (PowerShell):
Expand-Archive .\lakerunner-cli_Windows_x86_64.zip -DestinationPath .
# Move the binary somewhere on your PATH (create the folder if needed).
Move-Item .\lakerunner-cli.exe "$env:USERPROFILE\bin\lakerunner-cli.exe"
lakerunner-cli --helpAdd %USERPROFILE%\bin to your PATH via System Properties → Environment Variables (or setx PATH "$env:PATH;$env:USERPROFILE\bin" in a new shell) if it isn’t already.
Configuration
Environment Variables
Set the following environment variables to connect the CLI to your Lakerunner instance.
macOS / Linux:
export LAKERUNNER_QUERY_URL=<your-lakerunner-query-url>
export LAKERUNNER_API_KEY=<your-api-key>Windows (PowerShell):
# For the current session:
$env:LAKERUNNER_QUERY_URL = "<your-lakerunner-query-url>"
$env:LAKERUNNER_API_KEY = "<your-api-key>"
# To persist across sessions (takes effect in new shells):
setx LAKERUNNER_QUERY_URL "<your-lakerunner-query-url>"
setx LAKERUNNER_API_KEY "<your-api-key>"| Variable | Description | Required |
|---|---|---|
LAKERUNNER_QUERY_URL | URL of your Lakerunner query endpoint | Yes |
LAKERUNNER_API_KEY | API key for authentication | Yes |
These can also be passed per-command with --endpoint and --api-key flags.
Config File
The CLI supports an optional config file at ~/.lakerunner/config.yaml for defining presets and aliases.
# ~/.lakerunner/config.yaml
presets:
prod-errors:
- "environment:prod"
- "level:ERROR"
staging-all:
- "environment:staging"
aliases:
i: environment
svc: service
pod: k8s_pod_name
ns: k8s_namespace_namePresets are named sets of filters you can apply with -p. Aliases map short names to full attribute names — single-character aliases become short flags (e.g., -i), multi-character aliases become long flags (e.g., --svc).
Global Flags
These flags are available on all commands:
| Flag | Short | Description |
|---|---|---|
--quiet | -q | Suppress the “Querying logs…” banner and progress indicator |
--no-color | Disable colored output (auto-disabled on Windows and non-TTY stdout) | |
--endpoint | API endpoint URL (overrides LAKERUNNER_QUERY_URL) | |
--api-key | API key (overrides LAKERUNNER_API_KEY) |
Commands
logs get
Retrieve logs with flexible filtering. By default, returns the last hour of logs (newest first), limited to 1000 results.
lakerunner-cli logs getFlags
| Flag | Short | Description | Default |
|---|---|---|---|
--limit | Maximum number of results | 1000 | |
--start | -s | Start time (e.g., e-1h, 2024-01-01T00:00:00Z) | 1 hour ago |
--end | -e | End time (e.g., now, 2024-01-01T23:59:59Z) | now |
--app | -a | Filter by application/service name (comma-separated for multiple) | |
--level | -l | Filter by log level (ERROR, WARN, INFO, DEBUG, TRACE) | |
--filter | -f | Filter as key:value (repeatable) | |
--preset | -p | Use a named filter preset from config | |
--order | Sort order for results (newest or oldest) | newest | |
--output | -o | Output format (text, json, csv, tsv) | text |
--contains | -M | Message contains string | |
--not-contains | -N | Message does not contain string | |
--msg-regex | -R | Message matches regex | |
--msg-not-regex | -X | Message does not match regex | |
--columns | -c | Columns to display (comma-separated) | |
--query | Raw LogQL query (bypasses other filters) |
Time Ranges
The CLI supports flexible time expressions:
- Relative:
e-1h(1 hour before end),e-30m(30 minutes before end),now - Absolute: ISO 8601 format like
2024-01-01T00:00:00Z - Default: Last hour of data
Column Selection
Use --columns to customize output. Built-in column shortcuts:
| Shortcut | Description |
|---|---|
timestamp / ts | Log timestamp (nanosecond precision when available) |
level | Log level (color-coded in text output) |
service / svc | Service name |
pod | Kubernetes pod name |
message | Log message body |
Any log attribute (e.g., trace_id, k8s_namespace_name, container_image_tag) can also be used as a column name. Dotted names like resource.k8s.cluster.name are normalized to underscores automatically.
Examples
# Get the last 500 log entries
lakerunner-cli logs get --limit 500# Get ERROR logs from a specific service
lakerunner-cli logs get --level ERROR --app my-service# Filter by environment and region
lakerunner-cli logs get -f "environment:prod" -f "region:us-east-1"# Search for logs containing a specific string
lakerunner-cli logs get --contains "connection timeout"# Regex match on log messages
lakerunner-cli logs get --msg-regex "error|fatal|panic"# Use a preset
lakerunner-cli logs get --preset prod-errors# Custom time range with specific columns
lakerunner-cli logs get --start "e-30m" --columns "timestamp,level,service,message"# Export logs as JSON
lakerunner-cli logs get -o json# Export daily logs to CSV
lakerunner-cli logs get --start "2024-06-01T00:00:00Z" --end "2024-06-02T00:00:00Z" -o csv# Get oldest logs first
lakerunner-cli logs get --order oldest# Filter multiple services (comma-separated)
lakerunner-cli logs get -a "api-server,auth-service"# Raw LogQL query (see Query Language docs for syntax)
lakerunner-cli logs get --query '{service="my-service"} |= "error"'# Use aliases defined in config
lakerunner-cli logs get -i prod --svc my-servicelogs get-attr
Discover available log attributes (tag names) for a given time range. Useful for understanding what fields are available to filter on. Without any filters, this runs a fast metadata-only lookup. When any filter flag is provided, the CLI builds a LogQL selector and scopes the returned tag list to attributes present on rows that match — so you only see the attributes actually attached to your logs of interest.
lakerunner-cli logs get-attrFlags
| Flag | Short | Description |
|---|---|---|
--start | -s | Start time |
--end | -e | End time |
--app | -a | Filter by application/service name (comma-separated for multiple) |
--level | -l | Filter by log level |
--filter | -f | Filter as key:value (repeatable) |
--preset | -p | Use a named filter preset |
Example
# List all available attributes
lakerunner-cli logs get-attr
# List attributes present on ERROR logs from a specific service
lakerunner-cli logs get-attr --level ERROR --app my-servicelogs get-values
Get all possible values for a specific attribute. Takes the attribute name as an argument.
lakerunner-cli logs get-values <attribute_name>Flags
Same as logs get-attr.
Examples
# See all service names
lakerunner-cli logs get-values service
# See all environments
lakerunner-cli logs get-values environment
# See log levels in production
lakerunner-cli logs get-values level -f "environment:prod"presets list
List all configured filter presets from your config file.
lakerunner-cli presets listaliases list
List all configured aliases from your config file.
lakerunner-cli aliases listQuick Start
-
Download the CLI from the releases page .
-
Configure your environment (see Configuration for Windows PowerShell equivalents):
export LAKERUNNER_QUERY_URL=<your-lakerunner-query-url>
export LAKERUNNER_API_KEY=<your-api-key>- Query your logs:
lakerunner-cli logs get- Explore available attributes:
lakerunner-cli logs get-attr- Use
--helpfor more options:
lakerunner-cli --help
lakerunner-cli logs get --helpReach out to support@cardinalhq.io for support or to ask questions not answered in our documentation.