Skip to main content
The wit up and wit down commands provide a simple way to start and stop the complete wit platform, including the database, API server, and web UI.

​
wit up

Start the complete wit platform with a single command. 
wit up [options]

​
Options

OptionDescription
--port <port>API server port (default: 3000)
--db-port <port>Database port (default: 5432)
--no-webDon’t start the web UI
--no-dbUse external database (requires DATABASE_URL)
--data-dir <dir>Data directory (default: ~/.wit)
-h, --helpShow help message

​
Examples

# Start everything with defaults
wit up

# Start on custom port
wit up --port 8080

# Start without web UI
wit up --no-web

# Use custom data directory
wit up --data-dir ./my-data

# Use external database
DATABASE_URL=postgresql://... wit up --no-db

​
What wit up Does

When you run wit up, it:
  1. Starts PostgreSQL (via Docker) - unless --no-db is specified
  2. Runs database migrations - ensures schema is up to date
  3. Starts the API server - Git HTTP server and tRPC API
  4. Starts the web UI - React development server (unless --no-web)

​
Example Output

Starting wit platform...

  Starting database...
  Database started
  Running migrations...
  Migrations complete
  Starting API server...
  API server started
  Starting web UI...
  Web UI started

wit is running!

  Services:
    API:      http://localhost:3000
    Web UI:   http://localhost:5173
    Database: localhost:5432

  Stop with: wit down
  Logs at:   ~/.wit/logs

​
wit down

Stop all wit platform services. 
wit down [options]

​
Options

OptionDescription
--keep-dbDon’t stop the database
--remove-dataRemove all data (DESTRUCTIVE)
-h, --helpShow help message

​
Examples

# Stop everything
wit down

# Stop but keep database running
wit down --keep-db

# Stop and remove all data
wit down --remove-data

​
Example Output

Stopping wit platform...

  Web UI stopped
  API server stopped
  Database stopped

wit stopped

​
Data Directory

By default, wit stores all data in ~/.wit/: 
~/.wit/
  repos/       # Git repositories
  db/          # PostgreSQL data
  logs/        # Server and web logs
  wit.pid      # Process IDs for cleanup

​
Custom Data Directory

# Use a custom location
wit up --data-dir /path/to/data

# This creates:
# /path/to/data/repos/
# /path/to/data/db/
# /path/to/data/logs/

​
Requirements

​
Docker

wit up uses Docker to run PostgreSQL. Ensure Docker is installed and running: 
# Check Docker is available
docker --version

# If Docker isn't installed, either:
# 1. Install Docker Desktop
# 2. Use --no-db with an external database

​
External Database

If you can’t use Docker or prefer an external database: 
# Set DATABASE_URL
export DATABASE_URL=postgresql://user:pass@host:5432/wit

# Start without Docker database
wit up --no-db

​
Ports

Default ports used by wit:
ServiceDefault PortEnvironment Variable
API Server3000PORT
Web UI (Vite)5173-
PostgreSQL5432-

​
Custom Ports

# API on 8080, database on 5433
wit up --port 8080 --db-port 5433

​
Process Management

wit runs services in the background and tracks their process IDs: 
# Check if wit is running
ls ~/.wit/wit.pid

# View the PID file
cat ~/.wit/wit.pid

​
Checking Status

# See what's running
ps aux | grep wit

# Check logs
tail -f ~/.wit/logs/server.log
tail -f ~/.wit/logs/web.log

​
Logs

Logs are stored in ~/.wit/logs/:
FileContents
server.logAPI server output
web.logWeb UI (Vite) output

​
Viewing Logs

# Follow server logs
tail -f ~/.wit/logs/server.log

# View recent web logs
tail -100 ~/.wit/logs/web.log

# Search for errors
grep -i error ~/.wit/logs/*.log

​
Workflow Examples

​
Daily Development

# Start of day: start wit
wit up

# ... work on your projects ...

# End of day: stop wit
wit down

​
Quick API Testing

# Start just the API (no web UI)
wit up --no-web

# Test the API
curl http://localhost:3000/health

# Stop when done
wit down

​
Fresh Start

# Stop and remove all data
wit down --remove-data

# Start fresh
wit up

​
Keep Database Between Restarts

# Stop server but keep data
wit down --keep-db

# Later, start again (faster startup)
wit up

​
Troubleshooting

wit is already running
Stop it with: wit down
Either stop the existing instance:
wit down
wit up
Or if the PID file is stale:
rm ~/.wit/wit.pid
wit up

Docker not found
Docker is required to run the database.
Either install Docker or use an external database:
export DATABASE_URL=postgresql://...
wit up --no-db
Check if the port is in use:
lsof -i :5432
Either stop the conflicting process or use a different port:
wit up --db-port 5433
Check if port 5173 is in use:
lsof -i :5173
Check the web logs:
cat ~/.wit/logs/web.log
Try without web UI:
wit up --no-web
If wit down doesn’t stop services:
# Force kill by PID
cat ~/.wit/wit.pid | jq -r '.server, .web' | xargs kill -9

# Or stop Docker container manually
docker stop wit-postgres
docker rm wit-postgres

# Clean up PID file
rm ~/.wit/wit.pid

​
Environment Variables

VariableDescription
DATABASE_URLPostgreSQL connection string (when using —no-db)
PORTAPI server port (alternative to —port)
REPOS_DIRRepository storage directory
BETTER_AUTH_SECRETAuthentication secret (for production)