============
Command Line
============

``adac`` is also a command-line tool. Two front-ends drive one dispatch
layer, an interactive menu for newcomers and a scriptable flag interface for
power users and CI. Both assemble the same calls into the compiler, so
anything the menu does can be reproduced with flags.

The on-disk unit both speak is the IR config (``.json``) saved with
``adac.flamo_to_json``. It is plain data, so certifying and exporting need
no PyTorch.

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

The CLI's rendering and prompts are an optional extra, keeping the base
install light.

.. code-block:: console

   $ pip install -e ".[cli]"

The extra adds `rich <https://github.com/Textualize/rich>`_ and
`questionary <https://github.com/tmbo/questionary>`_. Without them the flag
interface still works and prints plain text; only the menu and the colour
need the extra.

The Interactive Menu
--------------------

Running ``adac`` with no arguments in a terminal opens the menu. It asks one
plain question at a time, every prompt has a sensible default, and enter
accepts it, so a newcomer can hold enter and get a working plugin out. The
menu offers five actions.

- **compile a model to a plugin.** Chooses a config, a plugin name, the
  macro-control knobs, and whether to build now or just generate the JUCE
  project. The stability verdict is shown before anything is exported, and a
  blocked verdict asks for explicit confirmation before proceeding in expert
  mode.
- **generate faust only.** Writes the ``.dsp`` and stops, no JUCE.
- **certify a model.** Prints the stability verdict in plain words.
- **hear it while it trains.** Prints the hot-reload setup steps.
- **inspect an ir config.** Summarises the node tree, channel counts,
  delays, matrices and embedded controls.

The Flag Interface
------------------

Every menu action is a subcommand, so scripts and CI run the same actions
without prompts.

.. code-block:: console

   $ adac certify model.json
   $ adac export model.json --out plugins/ --controls rt60,dry_wet --build
   $ adac generate model.json --out reverb.dsp
   $ adac inspect model.json

``--controls`` takes a comma-separated subset of ``rt60``, ``dry_wet`` and
``pre_delay``, the macro controls documented in the quick start.
``adac export`` refuses a blocked verdict unless ``--no-strict`` is given,
and ``--build`` also compiles and installs the plugin (macOS only). Each
subcommand documents its flags under ``--help``.

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

The exit code is a contract, so a pipeline can gate a release on stability.

.. list-table::
   :header-rows: 1
   :widths: 10 90

   * - Code
     - Meaning
   * - 0
     - the command succeeded and any verdict passed
   * - 1
     - a blocked verdict, or a tool failure during export
   * - 2
     - a user error, such as a missing file, invalid JSON, or an unknown
       control name

``adac certify`` exits 0 for ``certified-stable`` and ``marginally-stable``,
the same verdicts the strict exporter ships, and 1 otherwise.

Plain Output
------------

Colour, animation and the menu appear only on a terminal. When output is
piped, when running in CI, or when ``NO_COLOR`` is set, the CLI prints
plain parseable lines instead, one ``key: value`` pair per line, and errors
go to stderr.

.. code-block:: console

   $ adac certify model.json | cat
   verdict: certified-stable
   meaning: safe to ship