Clob commands

Use cwms-cli clob to upload, download, delete, update, and list CWMS clobs.

See also

Choose clob when you are working with text content such as configuration, JSON, XML, notes, templates, or other character-based files that you want the CLI to handle as text.

Choose blob when you are working with binary or media-oriented files such as PDFs, images, spreadsheets, or other content where media type and binary download behavior matter.

JSON deserves a specific note:

  • Use blob for JSON when you want the payload treated as a typed artifact with media type such as application/json so downstream clients can recognize and handle it as JSON.

  • Use clob for JSON when you mainly want to manage it as editable text through the CLI.

Quick reference

  • clob upload stores text content from a local file.

  • clob download writes the returned clob text to disk.

  • clob list and clob download send an API key if one is configured, unless --anonymous is used.

  • clob list --limit caps displayed rows, and sets the clob endpoint request page size unless --page-size is provided to override the fetch size.

  • clob upload --overwrite replaces an existing clob.

  • clob update supports partial updates and --ignore-nulls behavior.

Compared with blob, the clob command group is intentionally smaller:

  • no --media-type option

  • no directory upload mode

  • no generated IDs from file paths

  • update supports --ignore-nulls instead of blob-style media updates

Text behavior

cwms-cli clob is the text-oriented companion to blob.

  • Clob commands treat file content as text.

  • clob download writes UTF-8 text output to the target file.

  • Unlike blob, clob commands do not infer file extensions from a media type and do not perform binary decoding logic.

Example:

cwms-cli clob download \
  --clob-id FEBRUARY_SUMMARY_JSON \
  --dest ./downloads/february-summary.json \
  --office SWT

Auth and scope

Clob reads follow the same access pattern as blob reads.

  • If --api-key is provided, or CDA_API_KEY is set, cwms-cli sends that key.

  • If no key is provided, clob read commands default to anonymous access.

  • Use --anonymous on clob download or clob list to force an anonymous read even when a key is configured.

  • If a keyed read fails because the key scope is narrower than the content you are trying to view, the CLI logs a scope hint telling you to retry with --anonymous or remove the configured key.

Examples:

# Use configured key, if present
cwms-cli clob download --clob-id A.JSON --office SWT --api-root http://localhost:8082/cwms-data

# Force anonymous read even if CDA_API_KEY is set
cwms-cli clob download --clob-id A.JSON --office SWT --api-root http://localhost:8082/cwms-data --anonymous

# Anonymous list
cwms-cli clob list --office SWT --api-root http://localhost:8082/cwms-data --anonymous

List pagination

cwms-cli clob list can cap the local output and also control how many rows the CDA clob endpoint returns for the request.

  • --limit caps how many rows cwms-cli prints or writes.

  • When --limit is set, cwms-cli also uses that value as the clob endpoint request page_size.

  • Use --page-size to override the request size explicitly, especially if you want to fetch more rows than you plan to display.

Examples:

# Fetch and show up to 250 rows
cwms-cli clob list --office SWT --limit 250

# Fetch 500 rows from CDA but only show the first 50 locally
cwms-cli clob list --office SWT --limit 50 --page-size 500

Overwrite behavior

clob upload uses a normal Click flag pair:

  • --overwrite replaces an existing clob

  • --no-overwrite keeps the default behavior and fails if the clob already exists

Example:

cwms-cli clob upload \
  --input-file ./config/ops-template.json \
  --clob-id OPS_TEMPLATE_JSON \
  --overwrite \
  --office SWT

Update behavior

clob update is intended for text metadata and text file changes.

  • Use --description to replace the description field.

  • Use --input-file to replace the stored clob text.

  • Use --ignore-nulls to leave existing fields in place when the updated payload omits them.

Example:

cwms-cli clob update \
  --clob-id OPS_TEMPLATE_JSON \
  --input-file ./config/ops-template.json \
  --description "Updated operational template" \
  --ignore-nulls \
  --office SWT

Special-character IDs

Clob IDs that contain / or other characters that are not supported in the URL path:

  • cwms-cli detects those IDs automatically.

  • For path-sensitive operations such as download, update, and delete, the CLI uses the CDA fallback pattern with an ignored path segment and the clob ID in the query string.

  • You can still use the normal --clob-id argument from the CLI.

Example:

cwms-cli clob download \
  --clob-id "OPS/TEMPLATES/CONFIG.JSON" \
  --dest ./downloads/config.json \
  --office SWT

Blob vs clob

Use blob when you need:

  • binary-safe upload and download

  • media type tracking

  • explicit JSON-friendly media type handling such as application/json

  • extension inference on download

  • directory upload with regex matching and generated IDs

Use clob when you need:

  • plain text upload and download

  • human-readable file content handled as text

  • simple text updates without blob media handling

cwms-cli clob

Manage CWMS Clobs (upload, download, delete, update, list)

Usage

cwms-cli clob [OPTIONS] COMMAND [ARGS]...

Example Usage:

  • Download a clob by id to your local filesystem

  • Update a clob’s name/description/mime-type

  • Bulk list clobs for an office

delete

Delete a clob by ID

Usage

cwms-cli clob delete [OPTIONS]

Options

--clob-id <clob_id>

Required Clob ID to delete.

--dry-run

Show request; do not send.

-k, --api-key <api_key>

API key for CDA. Optional when a saved cwms-cli login token is available. Can also be provided by CDA_API_KEY.

-a, --api-root <api_root>

Required Api Root for CDA. Can be user defined or placed in a env variable CDA_API_ROOT

-o, --office <office>

Required Office to grab data for

--log-level <log_level>

Set logging verbosity (overrides default INFO).

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL

Environment variables

CDA_API_KEY

Provide a default for -k

CDA_API_ROOT

Provide a default for -a

OFFICE

Provide a default for -o

LOG_LEVEL

Provide a default for --log-level

download

Download a clob by ID

Usage

cwms-cli clob download [OPTIONS]

Options

--clob-id <clob_id>

Required Clob ID to download.

--dest <dest>

Destination file path. Defaults to clob-id.

--anonymous

Do not send credentials for this read request, even if they are configured.

--dry-run

Show request; do not send.

-k, --api-key <api_key>

API key for CDA. Optional when a saved cwms-cli login token is available. Can also be provided by CDA_API_KEY.

-a, --api-root <api_root>

Required Api Root for CDA. Can be user defined or placed in a env variable CDA_API_ROOT

-o, --office <office>

Required Office to grab data for

--log-level <log_level>

Set logging verbosity (overrides default INFO).

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL

Environment variables

CDA_API_KEY

Provide a default for -k

CDA_API_ROOT

Provide a default for -a

OFFICE

Provide a default for -o

LOG_LEVEL

Provide a default for --log-level

list

List clobs with optional filters and sorting

Usage

cwms-cli clob list [OPTIONS]

Options

--clob-id-like <clob_id_like>

LIKE filter for clob ID (e.g., *PNG).

--columns <columns>

Columns to show (repeat or comma-separate).

--sort-by <sort_by>

Columns to sort by (repeat or comma-separate).

--desc, --asc

Sort descending instead of ascending.

Default:

False

--limit <limit>

Max rows to show.

--page-size <page_size>

Max rows to request from the clob endpoint. Defaults to –limit when set.

--to-csv <to_csv>

If set, write results to this CSV file.

--anonymous

Do not send credentials for this read request, even if they are configured.

-k, --api-key <api_key>

API key for CDA. Optional when a saved cwms-cli login token is available. Can also be provided by CDA_API_KEY.

-a, --api-root <api_root>

Required Api Root for CDA. Can be user defined or placed in a env variable CDA_API_ROOT

-o, --office <office>

Required Office to grab data for

--log-level <log_level>

Set logging verbosity (overrides default INFO).

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL

Environment variables

CDA_API_KEY

Provide a default for -k

CDA_API_ROOT

Provide a default for -a

OFFICE

Provide a default for -o

LOG_LEVEL

Provide a default for --log-level

update

Update/patch a clob by ID

Usage

cwms-cli clob update [OPTIONS]

Options

--clob-id <clob_id>

Required Clob ID to update.

--dry-run

Show request; do not send.

--description <description>

New description JSON or text.

--input-file <input_file>

Optional file content to upload with update.

--ignore-nulls, --no-ignore-nulls

If true, null and empty fields in the provided clob will be ignored and the existing value of those fields left in place.

Default:

True

-k, --api-key <api_key>

API key for CDA. Optional when a saved cwms-cli login token is available. Can also be provided by CDA_API_KEY.

-a, --api-root <api_root>

Required Api Root for CDA. Can be user defined or placed in a env variable CDA_API_ROOT

-o, --office <office>

Required Office to grab data for

--log-level <log_level>

Set logging verbosity (overrides default INFO).

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL

Environment variables

CDA_API_KEY

Provide a default for -k

CDA_API_ROOT

Provide a default for -a

OFFICE

Provide a default for -o

LOG_LEVEL

Provide a default for --log-level

upload

Upload a file as a clob

Usage

cwms-cli clob upload [OPTIONS]

Options

--input-file <input_file>

Required Path to the file to upload.

--clob-id <clob_id>

Required Clob ID to create.

--description <description>

Optional description JSON or text.

--overwrite, --no-overwrite

If true, replace existing clob.

Default:

False

--dry-run

Show request; do not send.

-k, --api-key <api_key>

API key for CDA. Optional when a saved cwms-cli login token is available. Can also be provided by CDA_API_KEY.

-a, --api-root <api_root>

Required Api Root for CDA. Can be user defined or placed in a env variable CDA_API_ROOT

-o, --office <office>

Required Office to grab data for

--log-level <log_level>

Set logging verbosity (overrides default INFO).

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL

Environment variables

CDA_API_KEY

Provide a default for -k

CDA_API_ROOT

Provide a default for -a

OFFICE

Provide a default for -o

LOG_LEVEL

Provide a default for --log-level