CLI Usage Guide

Overview

The T3 Code CLI provides powerful options for running the server with custom configurations. Use it for development, production deployments, remote access, and CI/CD integration.

Basic Usage

Start the server with default settings:

t3

This starts the server on the first available port (starting at 8080) and opens your default browser.

CLI Flags

Mode

Set the runtime mode:

# Web mode (default) - serves web UI
t3 --mode web

# Desktop mode - optimized for Electron app
t3 --mode desktop

Desktop mode differences:

Binds to 127.0.0.1 by default (security)
Disables automatic browser opening
Uses fixed port (8080)

Port

Specify the HTTP/WebSocket server port:

# Custom port
t3 --port 3000

# Port must be between 1-65535
t3 --port 8080

In web mode, if the port is taken, the server finds the next available port. In desktop mode, it fails if the port is occupied.

Host

Bind to a specific network interface:

# Localhost only (default in desktop mode)
t3 --host 127.0.0.1

# All interfaces (remote access)
t3 --host 0.0.0.0

# Specific IP (e.g., Tailnet)
t3 --host 100.64.1.2

# IPv6
t3 --host '[::]'

Binding to 0.0.0.0 or [::] exposes the server to your network. Use --auth-token for security.

State Directory

Customize where T3 Code stores data:

# Custom state directory
t3 --state-dir ~/.t3-custom

# Project-specific state
t3 --state-dir ./t3-state

State directory contains:

SQLite database (projects, threads, messages)
keybindings.json configuration
Checkpoint metadata
Session state

Default locations:

macOS: ~/Library/Application Support/T3 Code
Windows: %APPDATA%\T3 Code
Linux: ~/.config/t3-code

Development URL

Proxy to a Vite dev server during development:

# Proxy to local Vite server
t3 --dev-url http://localhost:5173

# Custom dev server port
t3 --dev-url http://localhost:3000

Useful when developing the web interface.

Browser Control

Disable automatic browser opening:

# Don't open browser
t3 --no-browser

# Useful for server-only deployments
t3 --no-browser --host 0.0.0.0

Authentication

Require a token for WebSocket connections:

# Set auth token
t3 --auth-token secret123

# Generate secure token
t3 --auth-token $(openssl rand -hex 32)

The web interface must provide this token in the WebSocket URL:

ws://localhost:8080?token=secret123

Auth tokens are essential when binding to non-localhost interfaces.

Project Bootstrapping

Automatically create a project for the current directory:

# Auto-create project from cwd
t3 --auto-bootstrap-project-from-cwd

# Default enabled in web mode, disabled in desktop mode

The server creates a project named after the directory and starts a thread.

WebSocket Logging

Enable detailed WebSocket event logging:

# Log all WebSocket events
t3 --log-websocket-events

# Short alias
t3 --log-ws-events

Useful for debugging connection issues and event flow.

Environment Variables

All flags have environment variable equivalents:

# Mode
export T3CODE_MODE=web

# Port
export T3CODE_PORT=3000

# Host
export T3CODE_HOST=0.0.0.0

# State directory
export T3CODE_STATE_DIR=~/.t3-custom

# Dev URL
export VITE_DEV_SERVER_URL=http://localhost:5173

# No browser
export T3CODE_NO_BROWSER=true

# Auth token
export T3CODE_AUTH_TOKEN=secret123

# Auto-bootstrap
export T3CODE_AUTO_BOOTSTRAP_PROJECT_FROM_CWD=true

# WebSocket logging
export T3CODE_LOG_WS_EVENTS=true

CLI flags override environment variables.

Common Scenarios

Local Development

# Default setup
t3

# With dev server
t3 --dev-url http://localhost:5173

# Custom port with logging
t3 --port 3000 --log-ws-events

Remote Access

Bind to all interfaces

t3 --host 0.0.0.0 --port 8080

Add authentication

t3 --host 0.0.0.0 --auth-token $(openssl rand -hex 32)

Share the URL

echo "Connect to: http://YOUR_IP:8080?token=YOUR_TOKEN"

Tailscale Setup

# Get your Tailnet IP
tailscale ip -4

# Bind to Tailnet interface
t3 --host 100.64.1.2 --port 8080 --auth-token secure123

Access from any device on your Tailnet:

http://100.64.1.2:8080?token=secure123

Production Deployment

# Production settings
t3 \
  --mode web \
  --host 0.0.0.0 \
  --port 8080 \
  --no-browser \
  --auth-token $AUTH_TOKEN \
  --state-dir /var/lib/t3-code

Docker Container

FROM node:20-slim

WORKDIR /app
COPY . .
RUN bun install && bun run build

ENV T3CODE_HOST=0.0.0.0
ENV T3CODE_PORT=8080
ENV T3CODE_NO_BROWSER=true
ENV T3CODE_STATE_DIR=/data

EXPOSE 8080
VOLUME /data

CMD ["t3"]

Run:

docker run -p 8080:8080 -v t3-data:/data t3-code

Systemd Service

[Unit]
Description=T3 Code Server
After=network.target

[Service]
Type=simple
User=t3code
WorkingDirectory=/opt/t3-code
Environment="T3CODE_HOST=0.0.0.0"
Environment="T3CODE_PORT=8080"
Environment="T3CODE_NO_BROWSER=true"
Environment="T3CODE_AUTH_TOKEN=YOUR_TOKEN"
Environment="T3CODE_STATE_DIR=/var/lib/t3-code"
ExecStart=/usr/local/bin/t3
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable t3-code
sudo systemctl start t3-code

Security Best Practices

Always use authentication when exposing the server beyond localhost.

Generate Strong Tokens

# OpenSSL
openssl rand -hex 32

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Python
python -c "import secrets; print(secrets.token_hex(32))"

Restrict Network Access

Use firewall rules to limit connections:

# Allow only specific IPs
sudo ufw allow from 192.168.1.0/24 to any port 8080

# Deny all others
sudo ufw deny 8080

Use Reverse Proxy

Run behind nginx or Caddy for HTTPS:

server {
  listen 443 ssl;
  server_name t3.example.com;
  
  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;
  
  location / {
    proxy_pass http://localhost:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
  }
}

Debugging

Verbose Logging

Enable debug logs:

# Enable WebSocket event logging
t3 --log-ws-events

# Check server logs
tail -f ~/.config/t3-code/server.log

Connection Issues

Test WebSocket connection:

# Using websocat
websocat ws://localhost:8080

# With authentication
websocat "ws://localhost:8080?token=secret123"

Port Conflicts

Find process using a port:

# macOS/Linux
lsof -i :8080

# Windows
netstat -ano | findstr :8080

Kill the conflicting process or choose a different port.

Performance Tuning

State Directory on SSD

Store state on fast storage for better database performance:

t3 --state-dir /mnt/nvme/t3-state

Limit Concurrent Sessions

The server handles multiple projects and threads efficiently, but heavy workloads benefit from dedicated resources:

Light use (1-2 active threads): 2GB RAM, 2 CPU cores
Medium use (3-5 active threads): 4GB RAM, 4 CPU cores
Heavy use (6+ active threads): 8GB RAM, 8 CPU cores

Next Steps

Organize codebases in Project Management
Integrate version control with Git Workflow
Explore the Web Interface for daily use

Documentation Index

​Overview

​Basic Usage

​CLI Flags

​Mode

​Port

​Host

​State Directory

​Development URL

​Browser Control

​Authentication

​Project Bootstrapping

​WebSocket Logging

​Environment Variables

​Common Scenarios

​Local Development

​Remote Access

​Tailscale Setup

​Production Deployment

​Docker Container

​Systemd Service

​Security Best Practices

​Generate Strong Tokens

​Restrict Network Access

​Use Reverse Proxy

​Debugging

​Verbose Logging

​Connection Issues

​Port Conflicts

​Performance Tuning

​State Directory on SSD

​Limit Concurrent Sessions

​Next Steps

Overview

Basic Usage

CLI Flags

Mode

Port

Host

State Directory

Development URL

Browser Control

Authentication

Project Bootstrapping

WebSocket Logging

Environment Variables

Common Scenarios

Local Development

Remote Access

Tailscale Setup

Production Deployment

Docker Container

Systemd Service

Security Best Practices

Generate Strong Tokens

Restrict Network Access

Use Reverse Proxy

Debugging

Verbose Logging

Connection Issues

Port Conflicts

Performance Tuning

State Directory on SSD

Limit Concurrent Sessions

Next Steps