CLI Commands
============

LacePHP ships with a unified **php lace** command-line tool that helps you run your application, manage migrations, deploy code, scaffold files and even talk to the built-in AI.

Why the CLI Matters
-------------------
- **Speed**  
  One command to run tests, start servers, generate code or deploy—no manual copying or SSH sessions.  
- **Consistency**  
  Every developer on your team uses the same commands with the same options.  
- **Discoverability**  
  Running `php lace list` shows all available commands along with usage hints.

Getting Started
---------------
From your project root, run:

.. code-block:: bash

   php lace list

This prints every command LacePHP supports.

Basic Usage Pattern
~~~~~~~~~~~~~~~~~~~
Most commands follow:

.. code-block:: bash

   php lace <command> [action] [options]

- `<command>` is one of the built-in verbs (see below).  
- `[action]` refines the command (e.g. `create`, `run`, `watch`).  
- `[options]` or arguments (e.g. migration name, environment, port).

Detailed Command Guide
----------------------

- **list**  
  List all commands:  
  
  .. code-block:: bash  
        
        php lace list

- **app**  
  Run your application’s custom CLI tasks:  
  
  .. code-block:: bash  
        
        php lace app run

- **cobble**  
  Manage database migrations:  
  
  .. code-block:: bash  
        
        # Create a new migration  
        php lace cobble create AddUsersTable  
        # Run pending migrations  
        php lace cobble run

- **deploy**  
  Ship your app to staging or production:  
  
  .. code-block:: bash  
        
        php lace deploy  
        php lace deploy production

- **dev**  
  Watch route files and reload automatically:  
  
  .. code-block:: bash  
        
        php lace dev watch

- **enable**  
  Enable Composer usage and install dependencies:  
  
  .. code-block:: bash  
        
        php lace enable composer

- **metrics**  
  Clear collected metrics data:  
  
  .. code-block:: bash  
        
        php lace metrics reset

- **outsole**  
  Create the public symlink for assets:  
  
  .. code-block:: bash  
        
        php lace outsole link

- **route**  
  Manage and document routes:  
  
  .. code-block:: bash  
        
        # List all registered routes  
        php lace route list  
        # Generate OpenAPI spec  
        php lace route docs

- **dev:share**  
  Expose your local server over ngrok:  
  
  .. code-block:: bash  
        
        php lace dev:share 6916

- **stitch**  
  Scaffold code artifacts in `weave/`:  
  
  .. code-block:: bash  
        
        php lace stitch controller BlogController  
        php lace stitch model Post  
        php lace stitch route Comment API

- **timer**  
  Manage scheduled tasks via `aglet/schedule.json`:  
  
  .. code-block:: bash  
        
        php lace timer list  
        php lace timer run

- **tread**  
  Start the built-in PHP dev server:  
  
  .. code-block:: bash  
        
        php lace tread            # uses default host:port  
        php lace tread 0.0.0.0:8080

- **ai:activate**  
  Paste and activate your LaceAI license:  
  
  .. code-block:: bash  
        
        php lace ai:activate

- **ai:status**  
  Show current AI subscription status:  
  
  .. code-block:: bash  
        
        php lace ai:status

- **ai:scaffold**  
  Scaffold code from a prompt via AI:  
  
  .. code-block:: bash  
        
        php lace ai:scaffold "Create a REST API for tasks"

- **ai:rollback**  
  Undo the last AI scaffold operation:  
  
  .. code-block:: bash  
        
        php lace ai:rollback

- **ai:buddy**  
  Ask the AI buddy about a specific line of code:  
  
  .. code-block:: bash  
        
        php lace ai:buddy Controllers/BlogController.php 42 "Why is this null?"  

Best Practices
--------------
- **Use 'php lace list'** to explore commands.  
- **Read usage hints**: each command shows its expected pattern when you omit action or options.  
- **Create scripts**: combine multiple commands in a shell script (e.g. `deploy.sh`).  

.. warning::

   - Many commands affect your database or production servers—always double-check arguments before running.  
   - AI commands may modify your codebase—review and commit changes responsibly.  
   - CLI commands run with your user privileges—avoid destructive actions in hooks or custom tasks.  

|
|