Skip to main content

​
Overview

The start command launches the Better Auth Studio development server, providing a web-based interface for managing your Better Auth application.

​
Usage

better-auth-studio start [options]

​
Parameters

​
--port
string
default:"3002"
Port number to run the studio server on.Examples:
better-auth-studio start --port 3001
better-auth-studio start -p 8080
​
--host
string
default:"localhost"
Host address to bind the studio server to.Examples:
better-auth-studio start --host 0.0.0.0
better-auth-studio start -h 127.0.0.1
​
--config
string
Path to the auth configuration file. Can be relative or absolute.When not specified, the CLI automatically searches for config files in common locations:
  • auth.ts
  • src/auth.ts
  • lib/auth.ts
  • And other standard locations (up to 10 directories deep)
Examples:
# Relative path
better-auth-studio start --config ./src/lib/auth.ts

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

# Short form
better-auth-studio start -c ./custom-auth.ts
​
--geo-db
string
Path to MaxMind GeoLite2 database file (.mmdb) for IP geolocation features.Used to enhance session and event tracking with location data.Examples:
better-auth-studio start --geo-db ./data/GeoLite2-City.mmdb
better-auth-studio start --geo-db /var/lib/geolite/GeoLite2-City.mmdb
​
--watch
boolean
default:"false"
Enable watch mode to automatically reload the server when your auth config file changes.When enabled:
  • Monitors the auth configuration file for changes
  • Automatically restarts the server with the new configuration
  • Updates the browser UI via WebSocket (no manual refresh needed)
  • Perfect for development when iterating on your auth configuration
Examples:
better-auth-studio start --watch
better-auth-studio start -w

# Combine with other options
better-auth-studio start --watch --port 3001
If the auth config file cannot be located, watch mode will be automatically disabled with a warning message.
​
--no-open
boolean
default:"false"
Prevent the browser from automatically opening when the server starts.By default, the CLI opens your default browser to the studio URL. Use this flag to disable that behavior.Examples:
better-auth-studio start --no-open

​
Examples

​
Basic Usage

Start the studio with default settings: 
better-auth-studio start
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

Press Ctrl+C to stop the studio

​
Custom Port

Run on a different port: 
better-auth-studio start --port 3001

​
Development with Watch Mode

Enable auto-reload on config changes: 
better-auth-studio start --watch
Output when config changes: 
↻ Reloading Better Auth Studio (changed auth.ts)
✔ Reload complete (auth.ts)

​
Custom Configuration Path

Specify a non-standard auth config location: 
better-auth-studio start --config ./src/lib/auth.ts

​
Production-like Environment

Bind to all interfaces without opening browser: 
better-auth-studio start --host 0.0.0.0 --no-open

​
Full Example with All Options

Combine multiple options for a complete development setup: 
better-auth-studio start \
  --port 3001 \
  --host localhost \
  --config ./src/auth.ts \
  --watch \
  --geo-db ./data/GeoLite2-City.mmdb

​
Exit Codes

CodeDescription
0Server stopped gracefully (Ctrl+C)
1Failed to start server (auth config not found, port in use, etc.)

​
Error Conditions

​
Auth Config Not Found

If the CLI cannot locate your auth configuration file: 
# Error output
Error: Unable to find auth configuration file
Solution: Use the --config flag to specify the path explicitly.

​
Port Already in Use

If the specified port is already occupied: 
# Error output  
Error: Port 3002 is already in use
Solution: Use a different port with --port flag or stop the process using that port.

​
Watch Mode Without Config Path

If watch mode is enabled but config file cannot be located: 
# Warning output
⚠ Unable to locate your auth config file. Watch mode will be disabled for this session.
Solution: The server will start normally but without watch functionality.

​
Notes

The start command is designed for local development. For production deployments, see the Self-Hosting Guide.
Make sure your Better Auth configuration file exports a valid auth instance. The CLI validates the configuration before starting the server.

Build docs developers (and LLMs) love

Get started for freeTalk to us