chargelink trace
================

Inspect protocol traces and stream or export message-level evidence.

Reference syntax
----------------
.. code-block:: text

   usage: chargelink trace [-h] {show,live,filter,export,bookmark} ...

   positional arguments:
     {show,live,filter,export,bookmark}

   options:
     -h, --help            show this help message and exit

Subcommands
-----------
.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Subcommand
     - Purpose
   * - ``show``
     - Print a trace view from a case directory.
   * - ``live``
     - Stream a recent live trace view from a case directory.
   * - ``filter``
     - Filter a trace by message name or other selectors.
   * - ``export``
     - Export a trace as JSON, HTML, or CSV.
   * - ``bookmark``
     - Create a bookmark label for a runtime session.

show
----

Print a trace view from a case directory.

CLI help
~~~~~~~~
.. code-block:: text

   usage: chargelink trace show [-h] [--limit LIMIT] path

   positional arguments:
     path

   options:
     -h, --help     show this help message and exit
     --limit LIMIT

Production examples
~~~~~~~~~~~~~~~~~~~
**Show the most recent messages for a case.**

.. code-block:: bash

   chargelink trace show 'artifacts/evcc_campaign_runs/cl_int_iso20_ac_negative_realistic/case_1' --limit 25

**Show a second case to compare message ordering.**

.. code-block:: bash

   chargelink trace show 'artifacts/evcc_campaign_runs/cl_conf_iso2_dc_pnc_seed/case_1' --limit 25


live
----

Stream a recent live trace view from a case directory.

CLI help
~~~~~~~~
.. code-block:: text

   usage: chargelink trace live [-h] [--limit LIMIT] path

   positional arguments:
     path

   options:
     -h, --help     show this help message and exit
     --limit LIMIT

Production examples
~~~~~~~~~~~~~~~~~~~
**Stream the latest trace events from a case.**

.. code-block:: bash

   chargelink trace live 'artifacts/evcc_campaign_runs/cl_int_iso20_ac_negative_realistic/case_1' --limit 10

**Stream a second case.**

.. code-block:: bash

   chargelink trace live 'artifacts/evcc_campaign_runs/cl_conf_iso2_dc_pnc_seed/case_1' --limit 10


filter
------

Filter a trace by message name or other selectors.

CLI help
~~~~~~~~
.. code-block:: text

   usage: chargelink trace filter [-h] --message MESSAGE path

   positional arguments:
     path

   options:
     -h, --help         show this help message and exit
     --message MESSAGE

Production examples
~~~~~~~~~~~~~~~~~~~
**Filter a run for passing outcomes.**

.. code-block:: bash

   chargelink trace filter 'artifacts/evcc_campaign_runs/cl_int_iso20_ac_negative_realistic' --verdict 'pass'

**Filter a run for warnings.**

.. code-block:: bash

   chargelink trace filter 'artifacts/evcc_campaign_runs/cl_int_iso20_ac_negative_realistic' --verdict 'warn'


export
------

Export a trace as JSON, HTML, or CSV.

CLI help
~~~~~~~~
.. code-block:: text

   usage: chargelink trace export [-h] [--format {html,csv,json}] path output

   positional arguments:
     path
     output

   options:
     -h, --help            show this help message and exit
     --format {html,csv,json}

Production examples
~~~~~~~~~~~~~~~~~~~
**Export a case trace to CSV.**

.. code-block:: bash

   chargelink trace export 'artifacts/evcc_campaign_runs/cl_int_iso20_ac_negative_realistic/case_1' 'artifacts/traces/iso20_case.csv' --format 'csv'

**Export a case trace to HTML.**

.. code-block:: bash

   chargelink trace export 'artifacts/evcc_campaign_runs/cl_int_iso20_ac_negative_realistic/case_1' 'artifacts/traces/iso20_case.html' --format 'html'


bookmark
--------

Create a bookmark label for a runtime session.

CLI help
~~~~~~~~
.. code-block:: text

   usage: chargelink trace bookmark [-h] [--runtime-root RUNTIME_ROOT]
                                    [--label LABEL]
                                    session_id

   positional arguments:
     session_id

   options:
     -h, --help            show this help message and exit
     --runtime-root RUNTIME_ROOT
     --label LABEL

Production examples
~~~~~~~~~~~~~~~~~~~
**Bookmark a golden session.**

.. code-block:: bash

   chargelink trace bookmark 'session-001' --runtime-root '.tmp/runtime' --label 'golden'

**Bookmark a regression anchor session.**

.. code-block:: bash

   chargelink trace bookmark 'session-rc1' --runtime-root '.tmp/runtime' --label 'release-candidate'