Common API Arguments
====================

Several ``cwms-cli`` commands use the same CDA connection arguments. This page
documents those shared options in one place.

Shared options
--------------

- ``--office`` or ``OFFICE``
- ``--api-root`` or ``CDA_API_ROOT``
- ``--api-key`` or ``CDA_API_KEY``

Some commands also expose ``--api-key-loc`` / ``-kl`` to read the API key from
the first line of a file instead of passing the key inline. This is currently
available on the USGS subcommands and ``shefcritimport``.

These are the standard API inputs used by commands such as ``csv2cwms``.
If you have already run ``cwms-cli login``, cwms-cli will prefer the saved
access token from ``~/.config/cwms-cli/auth/federation-eams.json`` over an API
key. If no saved token is available, it falls back to the configured API key.

Environment setup
-----------------

.. raw:: html

   <details>
   <summary>Windows</summary>

.. code-block:: batch

   set CDA_API_KEY=your-api-key
   set CDA_API_ROOT=https://cwms-data.usace.army.mil/cwms-data
   set OFFICE=SWT

.. raw:: html

   </details>
   <details>
   <summary>Linux</summary>

.. code-block:: bash

   export CDA_API_KEY="your-api-key"
   export CDA_API_ROOT="https://cwms-data.usace.army.mil/cwms-data"
   export OFFICE="SWT"

.. raw:: html

   </details>

Notes
-----

- ``--office`` uses the ``OFFICE`` environment variable.
- ``--api-root`` uses the ``CDA_API_ROOT`` environment variable.
- ``--api-key`` uses the ``CDA_API_KEY`` environment variable.
- When ``--api-key-loc`` is provided for a command that supports it, the key
  read from that file takes precedence over ``--api-key`` and over a
  ``CDA_API_KEY`` value coming from the environment.
- When a saved login token exists, cwms-cli uses that token before consulting
  ``--api-key``, ``--api-key-loc``, or ``CDA_API_KEY``.
- For CDA-backed regex filters such as ``--like``, ``--location-kind-like``, and ``--timeseries-id-regex``, see the :doc:`CWMS Data API regular expression guide <cda_regex>`.
- Commands may still expose additional non-API options such as config files,
  timezone selection, or dry-run behavior.

Global logging and debug options
--------------------------------

Use the top-level ``cwms-cli --log-level`` option to control CLI log verbosity.

Valid values are:

- ``DEBUG``
- ``INFO``
- ``WARNING``
- ``ERROR``
- ``CRITICAL``

Example:

.. code-block:: bash

   cwms-cli --log-level DEBUG csv2cwms \
     --office SWT \
     --api-root https://cwms-data.usace.army.mil/cwms-data \
     --config cwmscli/commands/csv2cwms/tests/data/sample_config.json \
     --dry-run

If you were looking for a ``--debug-level`` flag, use ``--log-level DEBUG``
instead.

For certain exception paths, ``cwms-cli`` also checks ``CWMS_CLI_DEBUG``. When
that environment variable is set to ``1``, ``true``, ``yes``, or ``on``, the
CLI keeps the normal exception behavior instead of suppressing some friendly
error handling paths.

See also
--------

- :doc:`CLI reference <../cli>`
- :doc:`csv2cwms <csv2cwms>`