Skip to main content

​
Overview

Better Auth Studio provides a powerful CLI for managing your Better Auth applications. The CLI supports various options for customization, watch mode, and configuration.

​
Installation

You can use Better Auth Studio in multiple ways: 
npx better-auth-studio [command]
Recommended: Install as a dev dependency for project-specific versions and consistent behavior across your team.

​
Commands

​
start

Starts the Better Auth Studio development server. 
pnpx better-auth-studio start [options]
Default Behavior:
  • Starts server on http://localhost:3002
  • Automatically opens your browser
  • Auto-detects auth config file
  • Serves dashboard and API endpoints

​
init

Initializes Better Auth Studio for self-hosting in production. 
pnpx better-auth-studio init [options]
This creates:
  • studio.config.ts - Studio configuration file
  • API route handlers (Next.js App Router or Express)
  • Access control setup
Options:
  • --api-dir <path> - Custom app directory path for Next.js (e.g., “app” or “src/app”)
The init command auto-detects “app” or “src/app” directories for Next.js projects.

​
CLI Options

​
Port Configuration

pnpx better-auth-studio start --port <number>
Default: 3002 Examples: 
# Start on port 3001
pnpx better-auth-studio start --port 3001

# Start on port 8080
pnpx better-auth-studio start --port 8080
Use --port when port 3002 is already in use or when integrating with existing development setups.

​
Host Configuration

pnpx better-auth-studio start --host <string>
Default: localhost Examples: 
# Bind to all network interfaces
pnpx better-auth-studio start --host 0.0.0.0

# Use specific hostname
pnpx better-auth-studio start --host 192.168.1.100
Binding to 0.0.0.0 makes your studio accessible from other devices on your network. Only use this in trusted environments.

​
Custom Config Path

pnpx better-auth-studio start --config <path>
Default: Auto-detects from common locations The CLI searches for config files in this order:
  1. auth.ts
  2. src/auth.ts
  3. lib/auth.ts
  4. Other common locations
Examples: 
# Relative path
pnpx better-auth-studio start --config ./src/lib/auth.ts

# Absolute path
pnpx better-auth-studio start --config /path/to/project/auth.ts

# Custom filename
pnpx better-auth-studio start --config ./custom-auth.ts
Use --config when your auth file is in a non-standard location or when auto-detection fails.

​
Disable Auto-Open Browser

pnpx better-auth-studio start --no-open
Default: Browser opens automatically Example: 
# Start without opening browser
pnpx better-auth-studio start --no-open
Useful for CI/CD environments, remote development, or when you prefer to open the browser manually.

​
Watch Mode

pnpx better-auth-studio start --watch
Enables automatic server reload when your auth.ts configuration changes. Features:
  • Monitors auth config file for changes
  • Automatically restarts server
  • Updates browser UI via WebSocket (no manual refresh needed)
  • Shows file change notifications in terminal
Example: 
# Enable watch mode
pnpx better-auth-studio start --watch

# Watch mode with custom config
pnpx better-auth-studio start --watch --config ./src/lib/auth.ts
See Watch Mode for detailed information.

​
GeoIP Database Path

pnpx better-auth-studio start --geo-db <path>
Specifies path to MaxMind GeoLite2 database file (.mmdb) for IP geolocation in events and sessions. Example: 
pnpx better-auth-studio start --geo-db ./data/GeoLite2-City.mmdb
Download GeoLite2 databases from MaxMind

​
Combining Options

You can combine multiple options for advanced configurations:
1

Basic custom setup

pnpx better-auth-studio start --port 3001 --no-open
2

Development with watch mode

pnpx better-auth-studio start --watch --config ./src/auth.ts
3

Full custom configuration

pnpx better-auth-studio start \
  --port 3001 \
  --host 0.0.0.0 \
  --watch \
  --config ./src/lib/auth.ts \
  --no-open

​
Utility Commands

​
Check Version

pnpx better-auth-studio --version
Displays the current version of Better Auth Studio.

​
Show Help

pnpx better-auth-studio --help
Displays all available commands and options. 
# Command-specific help
pnpx better-auth-studio start --help
pnpx better-auth-studio init --help

​
Environment Setup

​
Prerequisites

Before using the CLI, ensure you have:
  • Required: Node.js v18 or higher
  • Check version: node --version
  • Update if needed: nodejs.org
  • Valid auth.ts configuration file
  • Better Auth installed and configured
  • Database adapter set up (Prisma, Drizzle, or SQLite)
  • Database connection string configured
  • Tables/schema migrated
  • Database adapter properly initialized

​
Terminal Output

When you start the studio, you’ll see detailed output: 
✔ Better Auth Studio is running!

🌐 Open your browser and navigate to: http://localhost:3002
📊 Dashboard available at: http://localhost:3002
🔧 API endpoints available at: http://localhost:3002/api
📋 Studio config found: studio.config.ts

👀 Watch mode enabled - config changes will reload automatically

Press Ctrl+C to stop the studio
Output includes:
  • Server status confirmation
  • Clickable URLs (in supported terminals)
  • Studio config detection status
  • Watch mode status (if enabled)
  • Events configuration status (if configured)
  • Database adapter information

​
Package.json Scripts

For convenience, add scripts to your package.json: 
{
  "scripts": {
    "studio": "better-auth-studio start",
    "studio:watch": "better-auth-studio start --watch",
    "studio:custom": "better-auth-studio start --port 3001 --config ./src/lib/auth.ts"
  },
  "devDependencies": {
    "better-auth-studio": "latest"
  }
}
Then run: 
pnpm studio
pnpm studio:watch
pnpm studio:custom

​
Next Steps

Watch Mode

Learn about automatic reload on config changes

Custom Branding

Customize studio appearance and metadata

Self-Hosting

Deploy studio in production

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us