CLI Commands Reference
The Gova backend provides a suite of CLI tools and service runners to manage the API lifecycle, event processing, and database schema. These tools are designed to be executed within a configured environment containing the necessary Docker and PgVector dependencies.
Service Runners
The application uses a "Runner" architecture to encapsulate different execution modes. The primary entry point for starting services is through the runner scripts located in src/runners/.
API Server Runner
The APIRunner initializes and executes the FastAPI application using uvicorn. It accepts standard Uvicorn configuration parameters as keyword arguments.
Usage:
# Example execution via a main entry point (standard implementation)
python -m src.main run-api --host 0.0.0.0 --port 8000 --workers 4
Configuration Options:
| Parameter | Type | Description |
| :--- | :--- | :--- |
| host | string | The network interface to bind to. |
| port | int | The port to listen on. |
| reload | bool | Enable auto-reload for development. |
| workers | int | Number of worker processes. |
Event Processor Runner
(Internal) While not explicitly exposed as a public-facing CLI, the system utilizes Kafka for moderator events (e.g., KAFKA_MODERATOR_EVENTS_TOPIC). Services consuming these events are typically started via specific runner commands to handle background tasks like content evaluation and automated moderation actions.
Database Management
Gova uses SQLAlchemy with a PostgreSQL backend (requiring the pgvector extension). CLI commands are used to initialize the vector-enabled database and manage relational schemas.
Initializing PgVector
Before running the backend, the database must be prepared with the pgvector extension.
# Connect to your PostgreSQL instance and run:
CREATE EXTENSION IF NOT EXISTS vector;
Schema Migrations
The system uses db_models.py to define the structural requirements for Users, Moderators, and Evaluation events. Database updates are handled via the CLI to ensure the following models are synchronized:
- Users: Manages authentication, Stripe IDs, and Discord OAuth payloads.
- Moderators: Stores configuration (
conf) and status for community bots. - EvaluationEvents: High-frequency table for storing
severity_scoreand vector-based context. - ActionEvents: Tracks the lifecycle of automated escalations (e.g.,
AWAITING_APPROVAL,COMPLETED).
Environment Configuration
The CLI tools rely on environment variables for service discovery and security. Ensure these are set before executing any runner:
| Variable | Description |
| :--- | :--- |
| KAFKA_MODERATOR_EVENTS_TOPIC | Destination for moderation event streams. |
| STRIPE_PRICING_PRO_PRICE_ID | The price ID for Pro tier checkout sessions. |
| DOMAIN / SUB_DOMAIN | Used for generating OAuth callback and payment URLs. |
| CUSTOMER_SUPPORT_EMAIL | Destination for /public/contact-us inquiries. |
Execution via Docker
For production-parity environments, use the built-in Docker CLI commands to wrap the runners.
# Build the backend container
docker build -t gova-backend .
# Run the API server within the container
docker run -p 8000:8000 --env-file .env gova-backend python -m src.runners.api_runner
Troubleshooting CLI Commands
Database Connection Issues
Ensure the PgVector extension is active. If the CLI fails to start due to missing types, verify your PostgreSQL version supports uuid-ossp and vector.
Discord OAuth Redirects
If the API runner starts but Discord authentication fails, ensure the SCHEME, SUB_DOMAIN, and DOMAIN variables match your Discord Developer Portal settings. The CLI uses these to build the RedirectResponse in the auth router.