CLI Reference
=============

Complete reference for all SpecAlign CLI commands.

Global Options
--------------

These options are available for all commands:

.. code-block:: text

   --help, -h          Show help message
   --version           Show version information
   --config PATH       Configuration file path
   --verbose, -v       Enable verbose output
   --quiet, -q         Suppress non-essential output

specalign run
-------------

Run the complete SpecAlign pipeline.

.. code-block:: bash

   specalign run [OPTIONS]

**Options:**

.. list-table::
   :widths: 30 70

   * - ``--config PATH``
     - Path to configuration file (default: config.json)
   * - ``--rules PATH``
     - Path to rules file (default: data/Stage_classified.md)
   * - ``--output PATH``
     - Output directory (default: output/)
   * - ``--max-seeds INT``
     - Maximum seeds to process
   * - ``--skip-specgen``
     - Skip specification generation phase
   * - ``--skip-redteam``
     - Skip red team testing phase

**Examples:**

.. code-block:: bash

   # Run complete pipeline
   specalign run --config config.json

   # Run with limited seeds
   specalign run --max-seeds 50

   # Skip spec generation (use existing)
   specalign run --skip-specgen

specalign generate
------------------

Generate specifications, instructions, and seeds.

specalign generate specs
~~~~~~~~~~~~~~~~~~~~~~~~

Generate specifications from rules.

.. code-block:: bash

   specalign generate specs RULES_PATH [OPTIONS]

**Arguments:**

- ``RULES_PATH``: Path to classified rules file

**Options:**

.. list-table::
   :widths: 30 70

   * - ``--num-specs INT``
     - Number of specifications to generate (default: 50)
   * - ``--min-rules INT``
     - Minimum rules per spec (default: 3)
   * - ``--max-rules INT``
     - Maximum rules per spec (default: 5)
   * - ``--output PATH``
     - Output file path

**Example:**

.. code-block:: bash

   specalign generate specs data/Stage_classified.md --num-specs 100

specalign generate instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Generate natural language instructions for specifications.

.. code-block:: bash

   specalign generate instructions SPECS_PATH [OPTIONS]

**Options:**

.. list-table::
   :widths: 30 70

   * - ``--topics INT``
     - Topics per specification (default: 3)
   * - ``--output PATH``
     - Output file path

**Example:**

.. code-block:: bash

   specalign generate instructions output/specs.json --topics 5

specalign generate seeds
~~~~~~~~~~~~~~~~~~~~~~~~

Generate seed prompts for testing.

.. code-block:: bash

   specalign generate seeds SPECS_PATH [OPTIONS]

**Options:**

.. list-table::
   :widths: 30 70

   * - ``--per-spec INT``
     - Seeds per specification (default: 10)
   * - ``--output PATH``
     - Output file path

**Example:**

.. code-block:: bash

   specalign generate seeds output/specs.json --per-spec 20

specalign generate all
~~~~~~~~~~~~~~~~~~~~~~

Run all generation steps.

.. code-block:: bash

   specalign generate all RULES_PATH [OPTIONS]

**Example:**

.. code-block:: bash

   specalign generate all data/Stage_classified.md \
       --num-specs 50 \
       --seeds-per-spec 10

specalign redteam
-----------------

Run red team adversarial testing.

.. code-block:: bash

   specalign redteam SEEDS_PATH [OPTIONS]

**Arguments:**

- ``SEEDS_PATH``: Path to seeds file

**Options:**

.. list-table::
   :widths: 30 70

   * - ``--max-rounds INT``
     - Maximum rounds per seed (default: 5)
   * - ``--max-seeds INT``
     - Maximum seeds to process
   * - ``--role-swap``
     - Enable role swapping
   * - ``--no-role-swap``
     - Disable role swapping
   * - ``--output PATH``
     - Output directory

**Examples:**

.. code-block:: bash

   # Basic red team run
   specalign redteam output/seeds.json

   # With role swapping and limited rounds
   specalign redteam output/seeds.json --role-swap --max-rounds 3

   # Process subset of seeds
   specalign redteam output/seeds.json --max-seeds 100

specalign analyze
-----------------

Analyze generated data and results.

.. code-block:: bash

   specalign analyze OUTPUT_DIR [OPTIONS]

**Options:**

.. list-table::
   :widths: 30 70

   * - ``--format TEXT``
     - Output format: summary, detailed, json (default: summary)
   * - ``--export PATH``
     - Export analysis to file

**Examples:**

.. code-block:: bash

   # Quick summary
   specalign analyze output/

   # Detailed analysis
   specalign analyze output/ --format detailed

   # Export to JSON
   specalign analyze output/ --format json --export analysis.json

specalign config
----------------

Configuration management commands.

specalign config init
~~~~~~~~~~~~~~~~~~~~~

Initialize configuration files.

.. code-block:: bash

   specalign config init [OPTIONS]

**Options:**

.. list-table::
   :widths: 30 70

   * - ``--minimal``
     - Create minimal configuration
   * - ``--force``
     - Overwrite existing files

**Example:**

.. code-block:: bash

   specalign config init
   specalign config init --minimal

specalign config validate
~~~~~~~~~~~~~~~~~~~~~~~~~

Validate configuration file.

.. code-block:: bash

   specalign config validate CONFIG_PATH

**Example:**

.. code-block:: bash

   specalign config validate config.json

specalign config show
~~~~~~~~~~~~~~~~~~~~~

Display current configuration.

.. code-block:: bash

   specalign config show [CONFIG_PATH]

specalign config env
~~~~~~~~~~~~~~~~~~~~

Show environment variable configuration.

.. code-block:: bash

   specalign config env

specalign providers
-------------------

API provider management.

specalign providers list
~~~~~~~~~~~~~~~~~~~~~~~~

List configured providers.

.. code-block:: bash

   specalign providers list

specalign providers add
~~~~~~~~~~~~~~~~~~~~~~~

Add a new provider.

.. code-block:: bash

   specalign providers add NAME [OPTIONS]

**Options:**

.. list-table::
   :widths: 30 70

   * - ``--base-url URL``
     - API base URL
   * - ``--api-key KEY``
     - API key
   * - ``--model MODEL``
     - Default model name

**Example:**

.. code-block:: bash

   specalign providers add mycloud \
       --base-url https://api.mycloud.com/v1 \
       --api-key sk-xxx \
       --model gpt-4-equivalent

specalign providers test
~~~~~~~~~~~~~~~~~~~~~~~~

Test provider connectivity.

.. code-block:: bash

   specalign providers test [NAME]

**Example:**

.. code-block:: bash

   specalign providers test openai
   specalign providers test  # Test all providers

specalign providers remove
~~~~~~~~~~~~~~~~~~~~~~~~~~

Remove a provider.

.. code-block:: bash

   specalign providers remove NAME

Exit Codes
----------

.. list-table::
   :widths: 20 80

   * - ``0``
     - Success
   * - ``1``
     - General error
   * - ``2``
     - Configuration error
   * - ``3``
     - API error
   * - ``4``
     - File not found