Command Line Interface
======================

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

Installation
------------

Install Gobstopper with CLI support:

.. code-block:: bash

   uv add "gobstopper[cli]"

Commands Overview
-----------------

.. list-table::
   :header-rows: 1
   :widths: 20 40 40

   * - 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
^^^^^^^^^^^

.. code-block:: bash

   # 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:**

.. code-block:: json

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

**production.toml:**

.. code-block:: toml

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

Use configs:

.. code-block:: bash

   # 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
^^^^^^^^^^^^^^^

.. list-table::
   :header-rows: 1
   :widths: 20 15 15 50

   * - 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
^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   # 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
^^^^^^^^^^^^^^^

.. code-block:: bash

   # 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
^^^^^^^^^^^^^^^^^^

.. code-block:: bash

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

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

Generate Background Tasks
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   # 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
^^^^^^^^^^^^^^^^

.. code-block:: bash

   # 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
^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   # 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:

.. code-block:: bash

   gobstopper version

Example output:

.. code-block:: text

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

Further Reading
---------------

For more detailed CLI documentation, see the `CLI Documentation <../docs/cli.md>`_ in the repository.