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_score and 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.