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 jsonInstall the published package with npm:
npm install --global @steipete/bslogOr use Bun:
bun add --global @steipete/bslogThe source build and development workflow require Bun 1.0 or newer.
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 20Structured 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.
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.
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-productionQueries 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.
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-productionFollow mode polls each source independently. trace applies the request ID as a requestId structured-field filter.
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.
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.
bun install --frozen-lockfile
bun run ci
bun run build:npmbun run ci checks formatting, linting, types, tests, and the npm bundle. The standalone Bun binary is built with bun run build.
MIT © Peter Steinberger.