Observer

CLI Reference

Observer provides a CLI for managing the server, database migrations, key generation, user administration, and development utilities.

Installation

# Build from source
just build

# Or install directly
go install github.com/lbrty/observer/cmd/observer@latest

Commands

serve

Start the HTTP server.

observer serve [flags]
FlagTypeDefaultDescription
--hoststringlocalhostServer host (overrides SERVER_HOST env)
--portint9000Server port (overrides SERVER_PORT env)

Examples:

# Start with defaults (localhost:9000)
observer serve

# Custom host and port
observer serve --host 0.0.0.0 --port 8080

# With environment configuration
DATABASE_DSN="postgres://..." REDIS_URL="redis://..." observer serve

In production builds, embedded migrations are applied automatically on startup. The server shuts down gracefully on SIGINT/SIGTERM with a 30-second timeout.

migrate

Database migration management.

migrate up

Apply all pending migrations.

observer migrate up [flags]
FlagTypeDefaultDescription
--pathstringmigrationsPath to migrations directory
# Apply all pending migrations
observer migrate up

# Use a custom migrations directory
observer migrate up --path ./db/migrations

migrate create

Create a new forward-only migration file.

observer migrate create [name] [flags]
FlagTypeDefaultDescription
--pathstringmigrationsPath to migrations directory
--sequintautoExplicit sequence number
# Create a migration (auto-numbered)
observer migrate create add_audit_log

# Create with explicit sequence number
observer migrate create add_audit_log --seq 25

migrate version

Show the current migration version.

observer migrate version [flags]
FlagTypeDefaultDescription
--pathstringmigrationsPath to migrations directory

keygen

Generate an RSA key pair for JWT signing.

observer keygen [flags]
FlagTypeDefaultDescription
--bitsint4096RSA key size (minimum 4096)
--outputstring.Output directory for key files

Examples:

# Generate keys in the current directory
observer keygen

# Generate 8192-bit keys in the keys/ directory
observer keygen --bits 8192 --output keys

Output files: private_key.pem (0600) and public_key.pem (0644).

create-admin

Create a platform administrator account.

observer create-admin [flags]
FlagTypeRequiredDescription
--emailstringyesAdmin email
--passwordstringyesAdmin password (min 8 chars)
--first-namestringnoFirst name
--last-namestringnoLast name
--phonestringnoPhone number

Examples:

# Create an admin with required fields
observer create-admin --email admin@example.com --password "s3cure-p4ss"

# With optional profile fields
observer create-admin \
  --email admin@example.com \
  --password "s3cure-p4ss" \
  --first-name Admin \
  --last-name User \
  --phone "+1234567890"

Connects to the database, hashes the password with Argon2id, and inserts the user with admin role (verified + active). Rejects duplicate emails and phone numbers.

seed

Seed the database with realistic mock data for development.

observer seed [flags]
FlagTypeDefaultDescription
--peopleint50Number of people per project
--projectsint2Number of projects
--seedint640Random seed (0 = random)

Examples:

# Seed with defaults (2 projects, 50 people each)
observer seed

# Custom counts
observer seed --projects 5 --people 200

# Reproducible seed
observer seed --seed 42
This command truncates ALL tables before inserting data. Do not run against a production database.

Creates reference data (countries, states, places, offices, categories), users with known passwords (password), projects with permissions, and populates people with support records, migration records, notes, pets, and households.

setup

Run first-time project setup interactively.

observer setup

This command:

  1. Creates a .env file with sensible defaults (prompts before overwriting)
  2. Creates required directories (keys/, data/uploads/)
  3. Generates a 4096-bit RSA key pair for JWT signing
  4. Prints next-steps instructions

Example output:

Created .env with default configuration.
Created directory: keys
Created directory: data/uploads
Generating 4096-bit RSA key pair...
Private key written to: keys/private_key.pem
Public key written to: keys/public_key.pem

Setup complete!

Next steps:
  1. Start Postgres and Redis:
     docker compose up -d

  2. Run database migrations:
     observer migrate up

  3. Create an admin user:
     observer create-admin --email admin@example.com --password "your-password"

  4. Start the server:
     observer serve

Common Workflows

First-time setup

# 1. Run interactive setup (creates .env, keys, directories)
observer setup

# 2. Start Postgres and Redis
docker compose up -d

# 3. Run migrations
observer migrate up

# 4. Create an admin user
observer create-admin --email admin@example.com --password "your-password"

# 5. Start the server
observer serve

For a full demo setup with sample data, see the demo setup guide.

Adding a new migration

# Create the migration file
observer migrate create add_audit_log

# Edit the generated SQL file
$EDITOR migrations/000025_add_audit_log.up.sql

# Apply it
observer migrate up

Seeding development data

# Make sure migrations are applied first
observer migrate up

# Seed with defaults
observer seed

# Login with: admin@example.com / password

Generating new JWT keys

# Generate new keys
observer keygen --output keys

# Update .env if paths differ from defaults
JWT_PRIVATE_KEY_PATH=keys/private_key.pem
JWT_PUBLIC_KEY_PATH=keys/public_key.pem

# Restart the server — existing tokens will be invalidated
observer serve
Prev
Frontend
Next
Testing