Leylines

Leylines is a local scoped log store for applications and coding agents. It captures structured entries with stable scopes, queryable properties, redaction before persistence, bounded retention, and deterministic CLI/JSON output.

It ships as one package with:

• a Node.js API for writing, querying, tailing, and expanding logs
• a ley CLI for agent and operator workflows
• a Vite development plugin plus browser and Tauri loggers

Leylines uses the built-in node:sqlite module, so it targets modern Node.js runtimes that include that API.

pnpm add leylines

Node API

import { openScopedLogs } from 'leylines'

const logs = openScopedLogs()
const logger = logs.logger({
  scope: 'checkout.cart',
  properties: { request: { id: 'req-123' } },
})

logger.info('cart opened', { properties: { cartId: 'cart-1' } })
logger.error('checkout failed', {
  properties: { cartId: 'cart-1' },
  error: new Error('payment declined'),
})

const page = logs.query({
  scopePrefix: 'checkout',
  minLevel: 'warn',
  properties: [{ path: 'cartId', equals: 'cart-1' }],
})

console.log(page.entries)
logs.close()

The Node API is disabled when NODE_ENV is production or a recognized test runner is active: it does not create a database, writes return undefined, and queries return no entries. Pass production: true only when production capture is intentional, or test: true in tests that explicitly exercise Leylines instrumentation.

Each entry has a stable id, timestamp, sequence, level, scope, message, metadata, structured properties, and optional error details. Supported levels are debug, info, warn, and error.

debug entries are hidden from default human-style queries unless includeDebug is set or levels: ['debug'] is requested explicitly.

CLI

The CLI reads the same inferred store as the Node API.

ley
ley --scope-prefix checkout --min-level warn
ley --property request.id=req-123
ley 'pay*' '!failed'
ley tail --print 20 --pretty
ley scopes
ley expand '<entry-id>:properties.payload'
ley path

Filtering supports:

• time: --since, --until
• entry boundaries: --before, --after
• levels: --level debug,info, --min-level warn, --include-debug
• scopes: --scope, --scope-prefix
• text: --text, --regex
• properties: --property path=value
• fuzzy terms: foo, '!foo', 'foo*', '*foo', 'dev.*'
• pagination: --limit

Use ley tail --print <count> to print the last matching entries before waiting for new ones. --limit still controls how many new entries are printed before the tail exits.

Default output is compact and chronological, which works well for quick human or agent triage. Add --pretty to recent or tail for spaced, color-coded terminal output. Use --json when output will be parsed, stored, compared, or when exact entry fields such as ids, sequences, and metadata are needed.

Vite

// vite.config.ts
import { defineConfig } from 'vite'
import { leylines } from 'leylines/vite'

export default defineConfig({
  plugins: [
    leylines({
      scope: 'browser',
      captureConsole: ['warn', 'error'],
      captureErrors: true,
      captureRejections: true,
      stripProduction: true,
    }),
  ],
})

The plugin registers a local ingestion endpoint and injects the browser logger during Vite serve mode. Production build capture is quiet by default. With stripProduction: true, production builds also remove standalone browser logger calls such as logger.info('router', 'route loaded').

Vite dev-server warnings and errors can also be captured directly from Vite's logger without changing normal terminal output:

leylines({
  viteLogger: {
    scope: 'dev.vite',
    levels: ['warn', 'error'],
  },
})

Vite warn and error keep their Leylines levels. Add info explicitly when using viteLogger; captured Vite info is stored as Leylines debug and is therefore hidden from default queries:

leylines({
  viteLogger: {
    levels: ['info', 'warn', 'error'],
  },
})

The captureViteLogger: true shorthand captures all three Vite levels. Use ley --scope-prefix dev.vite --include-debug --json to include captured Vite info entries.

ley --scope-prefix dev.vite --min-level warn --json

Tauri apps can forward @tauri-apps/plugin-log records through the browser logger connected by the Vite plugin:

pnpm add @tauri-apps/plugin-log

import { attachTauriLogger } from 'leylines/tauri'

const detachTauriLogs = attachTauriLogger()

Forwarded Tauri records use the tauri scope by default. Tauri trace records map to Leylines debug entries.

PostHog product metrics can be redirected into the same local store during development:

leylines({
  posthog: true,
})

posthog.init(projectKey, {
  api_host: '/__leylines/posthog',
})

Application code can also use the browser logger directly:

import { logger } from 'leylines/browser'

logger.connect({
  endpoint: '/__scoped_logs',
  scope: 'browser',
})

logger.info('router', 'route loaded', { route: '/settings' })

Redaction And Retention

Redaction runs before entries are persisted. Leylines redacts common secret-looking property names such as token, authorization, password, secret, cookie, and apiKey, plus credential-shaped values such as bearer tokens.

const logs = openScopedLogs({
  redaction: {
    rules: [{ name: /^stripe/i, replacement: '[STRIPE SECRET]' }],
  },
  retention: {
    maxEntries: 10_000,
    maxAgeMs: 7 * 24 * 60 * 60 * 1000,
  },
})

Retention runs during store maintenance: when a store opens, when it closes, and periodically during writes.

Large values are collapsed in default entries and can be retrieved later with logs.expand(id) or ley expand.

Agent Workflow

Start broad, discover scopes, then pivot through structured properties:

ley --limit 30
ley scopes
ley --scope-prefix checkout
ley --property request.id=req-123 --json

Agents can start with compact output when reading logs as context. Switch to JSON for automation or exact fields instead of inspecting SQLite files directly. Store schema and file layout are internal implementation details.

Documentation

• Getting Started gets a store, Node logger, CLI, and Vite browser capture working.
• Concepts explains entries, scopes, metadata, properties, redaction, retention, and collapsed values.
• Node API covers direct store usage, child loggers, queries, tailing, and expansion.
• Vite And Browser covers browser capture and singleton logger usage.
• CLI And Agent Workflows covers investigation patterns and JSON output for agents.
• PostHog Development Capture covers redirecting local PostHog events into Leylines.