Logging

llmist uses structured logging for debugging and monitoring.

Log Levels

Level	Priority	Use Case
`silly`	0	Most verbose, internal state dumps
`trace`	1	Detailed execution flow
`debug`	2	Debugging information
`info`	3	General operational info
`warn`	4	Warnings (default)
`error`	5	Errors that may need attention
`fatal`	6	Critical failures

Environment Variables

# Set log level
export LLMIST_LOG_LEVEL="debug"

Variable Reference

Variable	Description	Default
`LLMIST_LOG_LEVEL`	Minimum log level	`warn`
`LLMIST_LOG_FILE`	Write logs to a file instead of console	none
`LLMIST_LOG_RESET`	Truncate log file on startup (`true`/`false`)	`false`
`LLMIST_LOG_TEE`	Also write to stdout when file logging is active (`true`/`false`)	`false`

CLI Logging

Use command-line flags:

    # Set log level
    npx @llmist/cli agent "task" --log-level debug

    # Enable trace for maximum verbosity
    npx @llmist/cli agent "task" --log-level trace

Or configure in ~/.llmist/cli.toml:

[agent]
log-level = "debug"

Programmatic Configuration

Using .withLogger()

import { LLMist, createLogger } from 'llmist';

const logger = createLogger({
  minLevel: 'debug',
});

await LLMist.createAgent()
  .withLogger(logger)
  .askAndCollect('Your prompt');

Custom Logger

import { createLogger } from 'llmist';

const logger = createLogger({
  minLevel: 'debug',
  name: 'my-app',
});

// Log directly
logger.debug('Custom message', { data: 'value' });
logger.info('Agent started');
logger.error('Something failed', { error });

Silent Mode

Suppress all logging:

const logger = createLogger({
  minLevel: 'fatal', // Only fatal errors
});

Log Output Format

Console output:

[2024-01-15 10:23:45] DEBUG (llmist): LLM call started
  model: "anthropic:claude-sonnet-4-5"
  messageCount: 3
[2024-01-15 10:23:46] DEBUG (llmist): LLM call complete
  tokens: { input: 150, output: 80 }
  duration: 1234

File output (structured JSON):

{"level":"debug","time":"2024-01-15T10:23:45.123Z","msg":"LLM call started","model":"anthropic:claude-sonnet-4-5"}

Debugging with Logs

Capture LLM Interactions

    LLMIST_LOG_LEVEL=trace npx @llmist/cli agent "task" 2>&1 | tee debug.log

Debug Gadget Execution

const logger = createLogger({ minLevel: 'trace' });

await LLMist.createAgent()
  .withLogger(logger)
  .withGadgets(MyGadget)
  .askAndCollect('Test');

Trace output shows:

Gadget parameters received
Execution timing
Return values

File Logging with Console Tee

When running in containers (Docker, Kubernetes), you often need logs in both a file (for upload/archival) and stdout (for docker logs / log aggregation). Use teeToConsole to write to both:

import { createLogger } from 'llmist';

// Programmatic option
const logger = createLogger({
  minLevel: 'debug',
  teeToConsole: true,
});

Or via environment variables:

export LLMIST_LOG_FILE="/tmp/session.log"
export LLMIST_LOG_TEE="true"

File output is stripped of ANSI colors for clean plaintext; console output preserves colors.

Production Logging

const isProd = process.env.NODE_ENV === 'production';

const logger = createLogger({
  minLevel: isProd ? 'warn' : 'debug',
});

Integration with External Loggers

Wrap external loggers:

import pino from 'pino';

const pinoLogger = pino({ level: 'debug' });

// Create adapter
const logger = {
  debug: (msg, data) => pinoLogger.debug(data, msg),
  info: (msg, data) => pinoLogger.info(data, msg),
  warn: (msg, data) => pinoLogger.warn(data, msg),
  error: (msg, data) => pinoLogger.error(data, msg),
};

await LLMist.createAgent()
  .withLogger(logger)
  .askAndCollect('Task');