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

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

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 CWMS Data API regular expression guide.

  • 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:

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