Command Line Interface¶

Gobstopper includes a comprehensive CLI for rapid development and project management.

Installation¶

Install Gobstopper with CLI support:

uv add "gobstopper[cli]"

Commands Overview¶

Command	Description	Usage
`gobstopper run`	Run application with Granian server	Flask-like development server
`gobstopper init`	Create new Gobstopper projects	Interactive or with options
`gobstopper generate`	Generate components	Models, endpoints, tasks
`gobstopper run-tasks`	Run background task workers	Development and production
`gobstopper cleanup-tasks`	Clean up old completed tasks	Maintenance
`gobstopper version`	Show version and system info	Diagnostics

Running Your Application¶

The gobstopper run command provides a Flask-like interface with platform-optimized settings.

Basic Usage¶

# Run app:app on localhost:8000 (default)
gobstopper run

# With auto-reload for development
gobstopper run --reload

# Production with multiple workers
gobstopper run -w 4

# Custom host and port
gobstopper run -h 0.0.0.0 -p 3000

# Specific app module
gobstopper run myapp:application

Configuration Files¶

Create configuration files for different environments:

dev.json:

{
  "app": "example_app:app",
  "host": "127.0.0.1",
  "port": 5000,
  "workers": 1,
  "threads": 1,
  "reload": true
}

production.toml:

app = "example_app:app"
host = "0.0.0.0"
port = 8080
workers = 4
threads = 2
reload = false

Use configs:

# Load development config
gobstopper run --config dev

# Load production config
gobstopper run --config production

# Override config with CLI arguments
gobstopper run --config production -w 8

Command Options¶

Option	Short	Default	Description
`--host`	`-h`	`127.0.0.1`	Host to bind to
`--port`	`-p`	`8000`	Port to bind to
`--workers`	`-w`	`1`	Number of worker processes
`--threads`	`-t`	`1`	Number of threads per worker
`--reload`	`-r`	`false`	Enable auto-reload for development
`--config`	`-c`	`None`	Configuration file name (without extension)

Platform-Optimized Performance¶

The gobstopper run command automatically detects your platform:

🍎 ARM64/AArch64 (Apple Silicon): Uses single-threaded mode
💻 x86_64 (Intel/AMD): Uses multi-threaded mode

Built-in optimizations:

--log-level error - Minimal logging overhead
--backlog 16384 - Large connection backlog
--loop rloop - High-performance event loop
--respawn-failed-workers - Automatic worker recovery

Project Generation¶

Create New Projects¶

# Interactive project setup
gobstopper init

# Create specific project types
gobstopper init my-api --usecase data-science --structure modular
gobstopper init my-cms --usecase content-management --structure blueprints
gobstopper init dashboard --usecase real-time-dashboard --structure microservices

Available Use Cases¶

data-science - ML APIs with data processing
real-time-dashboard - Live dashboards with WebSocket streaming
content-management - Full CMS with admin interface
microservice - Lightweight service architecture

Available Structures¶

modular - Clean separation with modules (recommended)
blueprints - Flask-style blueprints
microservices - Distributed service architecture
single - Single-file applications

Component Generation¶

Generate Models¶

# Generate type-safe data model
gobstopper generate model User -f name:str -f email:str -f age:int

# With various field types
gobstopper generate model Article \\
  -f title:str \\
  -f content:str \\
  -f published:bool \\
  -f created_at:datetime

Generate Endpoints¶

# Basic endpoint
gobstopper generate endpoint /api/users -m GET

# Endpoint with authentication
gobstopper generate endpoint /api/users -m POST --auth

Generate Background Tasks¶

# Generate background task
gobstopper generate task process_data --category data

# Various task categories
gobstopper generate task send_email --category notifications
gobstopper generate task generate_report --category reports

Task Management¶

Run Task Workers¶

# Run workers for specific categories
gobstopper run-tasks --categories data,notifications --workers 2

# Run workers for all categories
gobstopper run-tasks --workers 4

Clean Up Old Tasks¶

# Clean tasks older than 7 days
gobstopper cleanup-tasks --days 7

# Clean tasks older than 2 months
gobstopper cleanup-tasks --months 2

Version Information¶

Get version and system information:

gobstopper version

Example output:

Gobstopper v0.1.0
High-performance async web framework
Built for Granian's RSGI interface