> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Usage Guide

> Master the T3 Code command-line interface for advanced configuration and automation

## 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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# Custom port
t3 --port 3000

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

<Note>
  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.
</Note>

### Host

Bind to a specific network interface:

```bash theme={null}
# 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 '[::]'
```

<Warning>
  Binding to `0.0.0.0` or `[::]` exposes the server to your network. Use `--auth-token` for security.
</Warning>

### State Directory

Customize where T3 Code stores data:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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
```

<Note>
  Auth tokens are essential when binding to non-localhost interfaces.
</Note>

### Project Bootstrapping

Automatically create a project for the current directory:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# Default setup
t3

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

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

### Remote Access

<Steps>
  <Step title="Bind to all interfaces">
    ```bash theme={null}
    t3 --host 0.0.0.0 --port 8080
    ```
  </Step>

  <Step title="Add authentication">
    ```bash theme={null}
    t3 --host 0.0.0.0 --auth-token $(openssl rand -hex 32)
    ```
  </Step>

  <Step title="Share the URL">
    ```bash theme={null}
    echo "Connect to: http://YOUR_IP:8080?token=YOUR_TOKEN"
    ```
  </Step>
</Steps>

### Tailscale Setup

```bash theme={null}
# 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

```bash theme={null}
# 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

```dockerfile theme={null}
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:

```bash theme={null}
docker run -p 8080:8080 -v t3-data:/data t3-code
```

### Systemd Service

```ini theme={null}
[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:

```bash theme={null}
sudo systemctl enable t3-code
sudo systemctl start t3-code
```

## Security Best Practices

<Warning>
  Always use authentication when exposing the server beyond localhost.
</Warning>

### Generate Strong Tokens

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```nginx theme={null}
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:

```bash theme={null}
# Enable WebSocket event logging
t3 --log-ws-events

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

### Connection Issues

Test WebSocket connection:

```bash theme={null}
# Using websocat
websocat ws://localhost:8080

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

### Port Conflicts

Find process using a port:

```bash theme={null}
# 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:

```bash theme={null}
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](/guides/project-management)
* Integrate version control with [Git Workflow](/guides/git-workflow)
* Explore the [Web Interface](/guides/web-interface) for daily use