Copier CLI
==========

.. flowtool:: Copier CLI
   :id: FLTL_COPIER
   :status: approved
   :tags: ubflow, installer

   Copier is the template rendering engine used for all installation and
   upgrade operations. It is invoked as ``copier copy`` / ``copier update``
   and reads ``copier.yml`` for prompts and hooks.
   Minimum required version: 9.0.0.

Usage
-----

The installer invokes Copier in four modes:

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

   * - Mode
     - Purpose
   * - ``copier copy``
     - Initial installation — renders the template into the target directory.
   * - ``copier update``
     - Upgrade an existing installation to a newer package version.
   * - ``--pretend``
     - Dry run — shows the diff without writing any files. Used before every upgrade.
   * - ``--overwrite``
     - Allows overwriting existing files. Requires explicit per-file confirmation.

Constraints
-----------

- Never pass ``--vcs-ref`` — versions are resolved from ``ubflow_package.json``, not git tags.
- The source path passed to Copier MUST be a directory. Never pass a zip path directly.
- Copier MUST NOT be invoked while ID conflicts or prerequisite failures are open.