DocsReferenceCLI

CLI Reference

The TopGun CLI provides a unified interface for development, testing, and cluster management. It drastically simplifies the developer experience by reducing onboarding from 30-60 minutes to under 5 minutes.

Zero Docker Required

The CLI defaults to SQLite storage, allowing you to start developing immediately without Docker or PostgreSQL setup.

Quick Start

terminal

# Clone and setup (2 minutes)
git clone https://github.com/topgunbuild/topgun.git
cd topgun
npx topgun setup --yes
npx topgun dev

# Server running at http://localhost:8080

Commands

topgun doctor

Check your environment for required dependencies and configuration.

terminal

npx topgun doctor

Checks performed:

Check	Required	Description
Node.js	Yes	Version 18 or higher
pnpm	Yes	Version 10.13.1 or higher
Docker	No	Optional (required for PostgreSQL mode)
Port 8080	Yes	Default server port must be available
Dependencies	Yes	node_modules must be installed
Build	Yes	packages/server/dist must exist
.env file	Yes	Environment configuration

Example output:

output

TopGun Environment Check

  ✓ Node.js: v20.10.0 (OK)
  ✓ pnpm: 10.13.1 (OK)
  ○ Docker: Not installed (optional for SQLite mode)
  ✓ Port 8080: Available
  ✓ Dependencies: Installed
  ✓ Build: Built
  ✓ .env file: Present

All checks passed! Ready to run.

topgun setup

Interactive project setup wizard.

terminal

# Interactive mode
npx topgun setup

# Non-interactive with defaults (SQLite)
npx topgun setup --yes

# Specify storage backend
npx topgun setup --storage postgres
npx topgun setup --storage sqlite
npx topgun setup --storage memory

Options:

Option	Description	Default
`-y, --yes`	Skip prompts, use defaults	`false`
`--storage <type>`	Storage backend: `sqlite`, `postgres`, `memory`	`sqlite`

Interactive mode prompts:

Storage backend - Choose between SQLite (no Docker), PostgreSQL (production), or Memory (testing)
k6 installation - Optional load testing tools
Dev Container - VS Code/Codespaces configuration

Example output:

output

TopGun Setup Wizard

[1/4] Creating .env file...
  ✓ .env created

[2/4] Installing dependencies...
  ✓ Dependencies installed

[3/4] Building packages...
  ✓ Build complete

[4/4] Skipping database (SQLite mode)
  ✓ SQLite will be used

Setup complete!

  Run:
    npx topgun dev

  Server will start at http://localhost:8080

topgun dev

Start the development server with live reload.

terminal

# Start with defaults
npx topgun dev

# Custom port
npx topgun dev --port 3000

# Skip database startup (PostgreSQL mode)
npx topgun dev --no-db

Options:

Option	Description	Default
`-p, --port <port>`	Server port	`8080`
`--no-db`	Skip database startup	`false`

The dev server uses tsx watch for automatic reloading when source files change.

topgun test

Run tests for specific packages or the entire project.

terminal

# Run all tests
npx topgun test

# Package-specific tests
npx topgun test core
npx topgun test client
npx topgun test server
npx topgun test react
npx topgun test adapters

# E2E tests
npx topgun test e2e

# k6 load tests
npx topgun test k6:smoke
npx topgun test k6:throughput

# With coverage
npx topgun test core --coverage

Available scopes:

Scope	Package	Description
`core`	`@topgunbuild/core`	CRDT, HLC, MerkleTree
`client`	`@topgunbuild/client`	Browser/Node SDK
`server`	`@topgunbuild/server`	WebSocket server
`react`	`@topgunbuild/react`	React hooks
`adapters`	`@topgunbuild/adapters`	Storage adapters
`e2e`	-	End-to-end tests
`k6:smoke`	-	Quick load test
`k6:throughput`	-	Full throughput test

topgun config

Manage project configuration.

terminal

# Show current configuration
npx topgun config --show

# Set transport mode
npx topgun config --transport ws
npx topgun config --transport http

# Set storage backend
npx topgun config --storage sqlite
npx topgun config --storage postgres

Options:

Option	Description
`--show`	Display current configuration
`--transport <type>`	Set transport: `ws`, `http`
`--storage <type>`	Set storage: `sqlite`, `postgres`, `memory`

Cluster Commands

topgun cluster:start

Start a local multi-node cluster for testing.

terminal

# Start 3-node cluster (default)
npx topgun cluster:start

# Custom node count
npx topgun cluster:start --nodes 5

Options:

Option	Description	Default
`-n, --nodes <count>`	Number of cluster nodes	`3`

topgun cluster:stop

Stop all running cluster nodes.

terminal

npx topgun cluster:stop

topgun cluster:status

Display the status of running cluster nodes.

terminal

npx topgun cluster:status

Debug Commands

topgun debug:crdt

CRDT debugging and inspection tools.

terminal

# Export CRDT state
npx topgun debug:crdt export --map users --output users.json

# Replay operations
npx topgun debug:crdt replay --map users

# Compare states
npx topgun debug:crdt diff --map users

Actions:

Action	Description
`export`	Export map state to JSON
`replay`	Replay operations for debugging
`diff`	Compare states between nodes

Options:

Option	Description
`--map <name>`	Target map name
`--output <file>`	Output file path

topgun search:explain

Explain search query scoring (BM25/RRF breakdown).

terminal

npx topgun search:explain --query "example search" --map documents

Options:

Option	Description
`--query <query>`	Search query to explain
`--map <name>`	Target map name

Environment Variables

The CLI respects the following environment variables (set in .env):

Variable	Description	Default
`STORAGE_MODE`	Storage backend	`sqlite`
`DB_PATH`	SQLite file path	`./topgun.db`
`SERVER_PORT`	Server port	`8080`
`DATABASE_URL`	PostgreSQL connection string	-
`DB_HOST`	PostgreSQL host	`localhost`
`DB_PORT`	PostgreSQL port	`5432`
`DB_USER`	PostgreSQL user	`topgun`
`DB_PASSWORD`	PostgreSQL password	-
`DB_NAME`	PostgreSQL database	`topgun`

Storage Modes

SQLite (Default)

Recommended for Development

SQLite requires no external dependencies and is perfect for local development, prototyping, and CI/CD testing.

Limitations:

Single-node only (no clustering)
Lower performance than PostgreSQL
Max ~500K records recommended

PostgreSQL

Recommended for production. Requires Docker or external PostgreSQL instance.

terminal

# Setup with PostgreSQL
npx topgun setup --storage postgres

# Requires Docker running
docker compose up -d postgres

Memory

For testing only. Data is lost on restart.

terminal

npx topgun setup --storage memory

Server API

Adapters