Skip to content

Command-Line Interface (CLI) Reference

castlecraft-engineer provides a command-line interface (CLI) for various development and operational tasks. This document outlines how to use the available CLI commands.

1. Invoking the CLI

The main entry point for the castlecraft-engineer CLI is through the Python module execution flag -m. You can invoke the CLI from the root of your project (where src/ is typically located or where the castlecraft_engineer package is importable) as follows:

python -m castlecraft_engineer.commands.entrypoint <command> [options]

Replace <command> with one of the available commands detailed below and [options] with any command-specific arguments.

2. Available Commands

The CLI is structured with sub-commands. Currently, the primary command available is bootstrap.

bootstrap Command

The bootstrap command is used to initialize the database schema.

  • Purpose: This command creates all necessary database tables based on the SQLModel metadata defined in your application. It's typically run once during the initial setup of your application or when new models are added and you need to update the schema in a development environment. For production environments, proper migration tools are usually recommended for schema changes after the initial setup.
  • Definition: The logic for this command is primarily located in castlecraft_engineer.database.commands.bootstrap_schema and it's made available to the CLI via castlecraft_engineer.commands.argparser.add_bootstrap_schema_parser.
  • Usage: 
    python -m castlecraft_engineer.commands.entrypoint bootstrap

  • Details: When executed, this command will:

    1. Establish a database connection using the SQL_ASYNC_CONNECTION_STRING (or SQL_CONNECTION_STRING if a synchronous version is targeted by the bootstrap logic) environment variable.
    2. Collect all table metadata from SQLModel classes that have been imported and registered with SQLModel.metadata.
    3. Execute SQLModel.metadata.create_all(engine) to create these tables in the database if they don't already exist.

    Ensure your .env file is correctly configured with the database connection string before running this command.

    Example Output (Conceptual): 

    INFO:castlecraft_engineer.database.commands:Bootstrapping database schema...
INFO:castlecraft_engineer.database.commands:Database schema bootstrapped successfully.

3. Extending the CLI / Discovering Commands

The CLI is designed to be extensible. New commands can be added by: 1. Implementing the command's logic (e.g., as a function in a relevant module). 2. Adding a new sub-parser for the command in castlecraft_engineer.commands.argparser.py (e.g., by creating a function similar to add_bootstrap_schema_parser). 3. Updating the main argument parser in get_parser() within argparser.py to include the new sub-parser. 4. Handling the new command in castlecraft_engineer.commands.entrypoint.py by dispatching to the appropriate function based on the parsed arguments.

To discover all available commands and their basic help messages, you can typically run: 

python -m castlecraft_engineer.commands.entrypoint --help
And for a specific command: 
python -m castlecraft_engineer.commands.entrypoint <command> --help

4. Common Arguments or Options

Currently, the CLI primarily uses sub-commands without extensive global options. Each sub-command might define its own specific arguments.

For instance, the bootstrap command itself does not take additional arguments as its behavior is largely controlled by environment variables (like the database connection string) and the defined SQLModels.

If global options (e.g., --verbose, --env-file) were to be added, they would be defined in the main ArgumentParser instance within castlecraft_engineer.commands.argparser.get_parser(). Always refer to the --help output for the most up-to-date information on available commands and options.