bslog 🔎 — Better Stack logs, without the SQL detour

bslog is a command-line client for querying Better Stack logs. It provides direct commands for common searches, a GraphQL-inspired query syntax for structured filtering, and raw ClickHouse SQL when needed.

bslog errors my-app-production --since 1h --limit 20
bslog search "timeout" my-app-production --where service=api --format json

Install

Install the published package with npm:

npm install --global @steipete/bslog

Or use Bun:

bun add --global @steipete/bslog

The source build and development workflow require Bun 1.0 or newer.

Quick start

Create a Better Stack Telemetry API token and Query API credentials, then export them in your shell:

export BETTERSTACK_API_TOKEN="your-telemetry-token"
export BETTERSTACK_QUERY_USERNAME="your-query-username"
export BETTERSTACK_QUERY_PASSWORD="your-query-password"

List your sources and fetch recent logs from one of them:

bslog sources list
bslog tail my-app-production --since 15m --limit 20

Structured queries need both credential types because bslog resolves source names through the Telemetry API before querying log data. See Authentication for credential setup and regional Query API hosts.

Everyday queries

The direct commands cover the usual debugging loop:

bslog errors my-app-production --since 1h
bslog warnings my-app-production --until 2026-08-02T12:00:00Z
bslog search "authentication failed" my-app-production
bslog tail my-app-production --follow

--since and --until accept relative values such as 30m, 1h, 2d, and 1w, plus dates understood by the JavaScript runtime. Add --fields dt,message,requestId to select fields or --where key=value to filter structured JSON values.

Output is available as pretty, json, table, or csv. A --jq filter switches output to JSON and runs the result through the local jq executable.

Normal queries search both hot and archived storage, so bounded historical searches include archived matches. --limit still caps the rows returned. Use --hot-only when low latency matters more than archived results. tail --follow is always hot-only because it polls for new entries.

Structured queries

Use the GraphQL-inspired syntax when the query shape is easier to express in one value:

bslog query "{ logs(level: 'error', since: '1h', limit: 50) { dt, message, requestId } }" --source my-app-production

Queries support limit, level, subsystem, since, until, between, search, where, and source. Fields may use dot or bracket paths such as metadata.proxy[0].status.

For queries that are already written in ClickHouse SQL, use bslog sql. Raw SQL talks directly to the Query API and does not resolve a source name first.

Multiple sources and traces

Pass comma-separated sources to merge results in descending timestamp order. Each merged row includes its source name.

bslog tail --sources api-production,worker-production --since 30m
bslog trace req-123 --sources api-production,worker-production

Follow mode polls each source independently. trace applies the request ID as a requestId structured-field filter.

Configuration

bslog stores non-secret settings in ~/.bslog/config.json. You can set a default source, query limit, output format, log level, or regional Query API URL with bslog config; credentials remain in environment variables.

See the CLI reference for every command, shared option, configuration key, time format, output mode, and built-in source alias.

Community

Use GitHub Issues for bugs, questions, and major-change proposals; pull requests are welcome. bslog is made by Peter Steinberger, built with Bun, uses Better Stack's APIs, and takes its query shape from GraphQL.

Development

bun install --frozen-lockfile
bun run ci
bun run build:npm

bun run ci checks formatting, linting, types, tests, and the npm bundle. The standalone Bun binary is built with bun run build.

License

MIT © Peter Steinberger.