Command-line usage
==================

Inspect a package
-----------------

Inventory a package without parsing or uploading clinical records:

.. code-block:: console

   $ acmad-upload inspect /path/to/package
   $ acmad-upload inspect /path/to/package --json

Validation is local and does not authenticate or change the destination.
Run all record types in dependency order with:

.. code-block:: console

   $ acmad-upload validate /path/to/package

The command prints issues beneath a heading for each record type and exits
with a non-zero status when any stage fails.

Upload a package
----------------

Upload the complete package in dependency order:

.. code-block:: console

   $ acmad-upload upload /path/to/package

Point package-level commands at the patient's complete directory tree. The
workbook fields, rather than folder names, provide record identifiers.

Uploads authenticate using the OIDC device flow. By default, the sign-in page
opens in a browser and tokens are saved in the operating system keyring. Use
``--no-open-browser`` to print the sign-in URL without opening it, or
``--memory-token`` to avoid saving tokens. TLS certificate verification is on
by default; ``--no-verify-tls`` is intended only for controlled development
environments.

Work with one record type
-------------------------

Every record type has matching ``validate`` and ``upload`` commands:

.. code-block:: console

   $ acmad-upload patient validate /path/to/package
   $ acmad-upload patient upload /path/to/package
   $ acmad-upload mocap-data validate /path/to/package

The available record types are:

.. list-table::
   :header-rows: 1
   :widths: 22 28 50

   * - Command
     - Input
     - Purpose
   * - ``patient``
     - ``patient_record.xlsx``
     - Patient master records, keyed by site patient identifier.
   * - ``diagnosis``
     - ``patient_record.xlsx``
     - Primary and secondary diagnoses.
   * - ``gait-assessment``
     - physical examination, function/PROMs, and mocap workbooks
     - Joins sibling workbooks into a gait assessment by natural key.
   * - ``function-assessment``
     - ``function_proms.xlsx``
     - GMFCS, FMS, and FAC measures.
   * - ``mocap-data``
     - ``mocap.xlsx``
     - One motion-capture session for each test condition.
   * - ``biomechanics-artifact``
     - files beneath each ``mocap_<condition>`` directory
     - Raw and derived motion-capture files with metadata and content hashes.
   * - ``physical-examination``
     - ``physical_exam.xlsx``
     - Anthropometrics and side-specific examination details.
   * - ``proms``
     - ``function_proms.xlsx``
     - FAQ, OFAQ, PODCI, MGaitEfficiency, Walk12, and GoalAssessment forms.
   * - ``surgery``
     - ``surgery.xlsx``
     - Surgery episodes and their numbered procedures.

Upload order and repeat runs
----------------------------

When running individual uploads, upload ``patient`` before dependent records,
``gait-assessment`` before its assessment family, and ``mocap-data`` before
``biomechanics-artifact``. Surgery depends only on the patient. The
package-level command applies this order automatically.

Uploads use each record type's natural key. Re-running an unchanged package is
therefore safe and is normally a no-op; unchanged biomechanics artefacts are
also skipped by content hash.

To see every option supported by a command, use ``--help``:

.. code-block:: console

   $ acmad-upload --help
   $ acmad-upload patient upload --help