Athena CLI Tooling

Relevant source files

The following files were used as context for generating this wiki page:

• src/athena_cli/commands/db.py
• src/athena_cli/commands/env.py
• pyproject.toml
• README.md
• AGENTS.md
• scripts/agent-worktree.sh
• tests/unit/athena_cli/test_packaging.py

The Athena CLI Tooling is a management interface designed to streamline the administration, environment configuration, and development workflows of the Athena private server. Built using the typer framework, the CLI provides a unified entry point for common tasks such as database migrations, environment variable generation, and service checks.

The tool is packaged as a console script named athena, which points to the athena_cli.main:main entry point. It is developed as a first-party package alongside the core server, ensuring tight integration with the project's configuration and persistence layers.
Sources: pyproject.toml:26, tests/unit/athena_cli/test_packaging.py:53-61, README.md:95-98

Core Command Structure

The CLI is organized into functional groups managed via subcommands. This hierarchy allows developers to manage specific subsystems like the database or environment configuration independently.

Command Groups Summary

Command Group	Description	Primary File
db	Database creation, migrations, and setup.	src/athena_cli/commands/db.py
env	Management of environment files (.env).	src/athena_cli/commands/env.py
config	Configuration validation and checks.	README.md:100

Sources: src/athena_cli/commands/db.py:16, src/athena_cli/commands/env.py:17, README.md:99-100

Database Management (db)

The db subcommand group handles the lifecycle of the PostgreSQL database. It integrates with alembic for migrations and utilizes internal infrastructure utilities to ensure the target database exists.

Database Workflow Logic

1. Creation: Checks for the existence of the database specified in the DATABASE_URL and creates it if missing.
2. Migration: Executes alembic upgrade head to apply all pending schema changes.
3. Setup: A convenience command that executes both creation and migration sequentially.

The diagram shows the logic flow for the setup command, including safety checks for production environments.
Sources: src/athena_cli/commands/db.py:84-131

Key Commands

• athena db create: Directly invokes create_database_if_missing. Sources: src/athena_cli/commands/db.py:34-45
• athena db migrate: Runs a ProcessRunner to execute Alembic commands. Sources: src/athena_cli/commands/db.py:51-64
• athena db setup: Orchestrates the full database initialization. Sources: src/athena_cli/commands/db.py:68-79

Environment Configuration (env)

The env module manages the generation and initialization of .env.{environment} files. It supports both interactive prompts (via inquirerpy) and non-interactive generation from existing process environments.

Environment Initialization Flow

The init command resolves the target environment (e.g., development, production) and collects necessary values for DSNs and API credentials.

The sequence demonstrates the interactive configuration of a new environment file.
Sources: src/athena_cli/commands/env.py:37-88

Configuration Categories

Section	Variables Configured	Logic
Database	DATABASE_URL	Constructs DSN from host, port, user, password.
Valkey	VALKEY_URL	Constructs DSN for the state/cache backend.
osu! API	BEATMAP_OFFICIAL_SOURCES_ENABLED, ...CLIENT_ID, ...SECRET	Manages official mirror credentials.

Sources: src/athena_cli/commands/env.py:91-107

Development Workflow Scripts

Beyond the athena CLI, the project includes shell scripts for specialized development tasks, particularly for managing parallel work.

Agent Worktree Management

The scripts/agent-worktree.sh utility is used to create isolated Git worktrees for coding agents or developers. It copies relevant local files (like .env files) that are otherwise ignored by Git, using rules defined in .worktreeinclude.

The flow shows how agent-worktree.sh prepares an isolated environment while maintaining local configuration.
Sources: scripts/agent-worktree.sh:1-35, AGENTS.md:275-285

Continuous Integration (CI) Script

The scripts/ci.sh script provides a local quality gate. It wraps several tools:

• quality: Runs ruff, basedpyright, and import-linter.
• test: Runs pytest (manages a temporary Valkey instance if needed).
• fix: Applies automatic ruff formatting and lint fixes.

Sources: scripts/ci.sh:11-50, AGENTS.md:144-150

Conclusion

The Athena CLI Tooling serves as the primary operational interface for the project, abstracting the complexities of environment setup and database management. By providing both interactive commands and automated scripts for worktree management, the tooling ensures a consistent and efficient workflow for both human contributors and AI agents.
Sources: README.md:95-104, AGENTS.md:273-280