Platform Commands

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

Option	Description
`--port <port>`	API server port (default: 3000)
`--db-port <port>`	Database port (default: 5432)
`--no-web`	Don’t start the web UI
`--no-db`	Use external database (requires DATABASE_URL)
`--data-dir <dir>`	Data directory (default: ~/.wit)
`-h, --help`	Show 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:

Starts PostgreSQL (via Docker) - unless --no-db is specified
Runs database migrations - ensures schema is up to date
Starts the API server - Git HTTP server and tRPC API
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

Option	Description
`--keep-db`	Don’t stop the database
`--remove-data`	Remove all data (DESTRUCTIVE)
`-h, --help`	Show 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:

Service	Default Port	Environment Variable
API Server	3000	`PORT`
Web UI (Vite)	5173	-
PostgreSQL	5432	-

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

File	Contents
`server.log`	API server output
`web.log`	Web 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

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

Database failed to start

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

Web UI failed to start

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

Server won't stop

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

Variable	Description
`DATABASE_URL`	PostgreSQL connection string (when using —no-db)
`PORT`	API server port (alternative to —port)
`REPOS_DIR`	Repository storage directory
`BETTER_AUTH_SECRET`	Authentication secret (for production)

wit serve - Start just the API server
wit token - Create API tokens
wit collaborator - Manage collaborators

Get Started

Commands

Visual Interfaces

AI & Intelligence

Workflows

GitHub & Team

Advanced

Configuration

Platform

Architecture

Database

Platform Commands

wit up

Options

Examples

What wit up Does

Example Output

wit down

Options

Examples

Example Output

Data Directory

Custom Data Directory

Requirements

Docker

External Database

Ports

Custom Ports

Process Management

Checking Status

Logs

Viewing Logs

Workflow Examples

Daily Development

Quick API Testing

Fresh Start

Keep Database Between Restarts

Troubleshooting

Environment Variables

​wit up

​Options

​Examples

​What wit up Does

​Example Output

​wit down

​Options

​Examples

​Example Output

​Data Directory

​Custom Data Directory

​Requirements

​Docker

​External Database

​Ports

​Custom Ports

​Process Management

​Checking Status

​Logs

​Viewing Logs

​Workflow Examples

​Daily Development

​Quick API Testing

​Fresh Start

​Keep Database Between Restarts

​Troubleshooting

​Environment Variables

​Related Commands

wit up

Options

Examples

What wit up Does

Example Output

wit down

Options

Examples

Example Output

Data Directory

Custom Data Directory

Requirements

Docker

External Database

Ports

Custom Ports

Process Management

Checking Status

Logs

Viewing Logs

Workflow Examples

Daily Development

Quick API Testing

Fresh Start

Keep Database Between Restarts

Troubleshooting

Environment Variables

Related Commands