stacks-repl

name	stacks-repl
description	Use when working with the Stacks REPL — interactive TypeScript sessions, tinker sessions, debugging, or exploring the framework interactively. Covers @stacksjs/repl and @stacksjs/tinker.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

Stacks REPL / Tinker

Key Paths

• REPL package: storage/framework/core/repl/src/
• Tinker package: storage/framework/core/tinker/src/
• Packages: @stacksjs/repl, @stacksjs/tinker

API

import { startRepl } from '@stacksjs/repl'

interface ReplConfig extends TinkerConfig {
  loadFile?: string  // Path to file to preload before starting
}

async function startRepl(config: ReplConfig): Promise<{ exitCode: number }>

How It Works

1. If config.loadFile is specified, reads the file content
2. Merges file content into config.eval for evaluation
3. Starts an interactive Bun REPL session with all framework modules available
4. Returns the process exit code when the session ends

Re-exports from @stacksjs/tinker

import {
  startTinker,      // Start a tinker session
  tinkerEval,       // Evaluate an expression
  tinkerPrint,      // Print a result
  getHistoryPath,   // Get REPL history file path
  readHistory,      // Read command history
  appendHistory,    // Append to command history
  clearHistory,     // Clear command history
} from '@stacksjs/repl'

import type { TinkerConfig } from '@stacksjs/repl'

CLI Commands

buddy tinker                    # Start interactive REPL session
buddy tinker --load file.ts     # Preload a file before starting

Usage

Inside the REPL, all framework modules are available:

// Query the database
const users = await db.selectFrom('users').get()

// Use models
const post = await Post.find(1)

// Access config
console.log(config.app.name)

// Use faker for quick testing
const email = faker.internet.email()

Gotchas

• Tinker is the user-facing command, REPL is the engine — buddy tinker calls startRepl() under the hood
• All framework imports available — models, database, config, faker, etc. are preloaded
• History is persisted — REPL history is saved to disk via getHistoryPath()
• File preloading — use loadFile to run setup code before entering interactive mode
• Bun runtime — the REPL runs in Bun's JavaScript runtime, not Node.js