Infrastructure CLI Reference

Manage services, databases, background jobs, and logs with the infrastructure CLI domain. Control your SystemPrompt runtime environment.

On this page

The infra domain manages your SystemPrompt runtime environment. It controls services, databases, background jobs, and logs.

Why Infrastructure Exists

Running AI agents requires:

  • Services - API servers, schedulers, workers
  • Database - PostgreSQL for persistence
  • Jobs - Scheduled and background tasks
  • Logs - Debugging and monitoring

The infra domain gives you control over these runtime components.

Quick Reference

Subcommand Description
infra services Service lifecycle management
infra db Database operations
infra jobs Background job management
infra logs Log viewing and streaming

Services

Manage the SystemPrompt service lifecycle.

Check Status

# Show all service statuses
systemprompt infra services status

# JSON output
systemprompt --json infra services status

Output:

┌─────────────┬──────────┬───────┬─────────────────────┐
│ Service     │ Status   │ PID   │ Uptime              │
├─────────────┼──────────┼───────┼─────────────────────┤
│ api         │ running  │ 12345 │ 2h 30m              │
│ scheduler   │ running  │ 12346 │ 2h 30m              │
│ worker      │ running  │ 12347 │ 2h 30m              │
│ database    │ running  │ 12340 │ 2h 31m              │
└─────────────┴──────────┴───────┴─────────────────────┘

Start Services

# Start all services
systemprompt infra services start --all

# Start specific service
systemprompt infra services start api
systemprompt infra services start scheduler

# Start with verbose output
systemprompt infra services start --all -v

Stop Services

# Stop all services
systemprompt infra services stop --all

# Stop specific service
systemprompt infra services stop api

# Force stop (SIGKILL)
systemprompt infra services stop --all --force

Restart Services

# Restart specific service
systemprompt infra services restart api

# Restart all services
systemprompt infra services restart --all

Service Types

Service Purpose
api HTTP API server
scheduler Job scheduler
worker Background task worker
database PostgreSQL (Docker)

Database

Manage the PostgreSQL database.

Check Status

# Database status
systemprompt infra db status

Output:

{
  "connected": true,
  "host": "localhost",
  "port": 5432,
  "database": "systemprompt_dev",
  "version": "PostgreSQL 15.4",
  "migrations": {
    "applied": 42,
    "pending": 0
  }
}

Run Migrations

# Apply pending migrations
systemprompt infra db migrate

# Check migration status
systemprompt infra db status

Run Queries

# Execute read-only query
systemprompt infra db query "SELECT COUNT(*) FROM users"

# JSON output
systemprompt --json infra db query "SELECT * FROM agents LIMIT 5"

# Execute write query
systemprompt infra db execute "UPDATE settings SET value = 'new' WHERE key = 'theme'"

View Tables

# List all tables
systemprompt infra db tables

# Describe table structure
systemprompt infra db describe users

# Count rows
systemprompt infra db count users

Database Introspection

# Show indexes
systemprompt infra db indexes users

# Show table size
systemprompt infra db size

# Validate schema
systemprompt infra db validate

Database Admin

# Backup database
systemprompt infra db backup --output ./backup.sql

# Restore database
systemprompt infra db restore --input ./backup.sql

# Reset database (dangerous!)
systemprompt infra db reset --yes

Jobs

Manage scheduled and background jobs.

List Jobs

# List all scheduled jobs
systemprompt infra jobs list

# JSON output
systemprompt --json infra jobs list

Output:

┌──────────────────┬───────────────┬──────────┬─────────────────────┐
│ Job ID           │ Schedule      │ Status   │ Last Run            │
├──────────────────┼───────────────┼──────────┼─────────────────────┤
│ cleanup_sessions │ 0 0 * * *     │ enabled  │ 2026-01-30 00:00:00 │
│ sync_analytics   │ */15 * * * *  │ enabled  │ 2026-01-30 10:30:00 │
│ backup_db        │ 0 2 * * *     │ enabled  │ 2026-01-30 02:00:00 │
└──────────────────┴───────────────┴──────────┴─────────────────────┘

Run Job Manually

# Run job now
systemprompt infra jobs run cleanup_sessions

# Run with verbose output
systemprompt infra jobs run sync_analytics -v

View Job History

# View job history
systemprompt infra jobs history

# Filter by job
systemprompt infra jobs history --job cleanup_sessions

# Limit results
systemprompt infra jobs history --limit 20

View Job Logs

# View logs for specific job run
systemprompt infra jobs logs cleanup_sessions

# Show last N lines
systemprompt infra jobs logs cleanup_sessions --lines 100

Enable/Disable Jobs

# Disable job
systemprompt infra jobs disable cleanup_sessions

# Enable job
systemprompt infra jobs enable cleanup_sessions

Logs

View and stream application logs.

View Logs

# View recent logs
systemprompt infra logs

# Filter by service
systemprompt infra logs --service api
systemprompt infra logs --service scheduler

# Show specific number of lines
systemprompt infra logs --lines 100

Filter by Level

# Show only errors
systemprompt infra logs --level error

# Show warnings and above
systemprompt infra logs --level warn

# Available levels: trace, debug, info, warn, error

Follow Logs

# Stream logs in real-time
systemprompt infra logs --follow

# Follow specific service
systemprompt infra logs --service api --follow

Search Logs

# Search for pattern
systemprompt infra logs --search "error"

# Search with regex
systemprompt infra logs --search "user_[0-9]+"

Log Tracing

# Trace specific request
systemprompt infra logs trace --request-id req_abc123

# Trace by user
systemprompt infra logs trace --user-id user_xyz

Common Workflows

Starting Development Environment

# Start all services
systemprompt infra services start --all

# Check everything is running
systemprompt infra services status

# Run any pending migrations
systemprompt infra db migrate

Debugging Issues

# Check service status
systemprompt infra services status

# View recent errors
systemprompt infra logs --level error

# Follow logs for specific service
systemprompt infra logs --service api --follow

Database Maintenance

# Check database status
systemprompt infra db status

# Backup before changes
systemprompt infra db backup --output ./backup-$(date +%Y%m%d).sql

# Run migrations
systemprompt infra db migrate

# Validate schema
systemprompt infra db validate

Monitoring Jobs

# Check job status
systemprompt infra jobs list

# View recent runs
systemprompt infra jobs history --limit 10

# Check if any jobs failed
systemprompt infra jobs history --status failed

Playbooks:

  • systemprompt core playbooks show cli_services - Service management
  • systemprompt core playbooks show cli_database - Database operations
  • systemprompt core playbooks show cli_jobs - Job scheduling
  • systemprompt core playbooks show cli_logs - Log management

Guides:

Previous Next
Core CLI Admin CLI