Blob commands

Note

Maintainers: Charles Graham

Use cwms-cli blob to upload, download, delete, update, and list CWMS blobs.

See also

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

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

NOTE:

  • Use blob when you want to set or preserve a media type such as application/json so API consumers and JavaScript clients can treat the payload as JSON (or other media types).

  • Use clob when you mainly want to manage text through the CLI and don’t care about media types.

Quick reference

  • blob upload supports single-file upload and directory upload.

  • blob download writes the returned blob content to disk using the server media type when possible.

  • blob list and blob download send a saved login token if one exists, otherwise an API key if one is configured, unless --anonymous is used.

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

  • Directory upload stops before sending anything if generated blob IDs would collide.

  • blob upload --overwrite: To replace existing blobs.

Compared with clob, the blob command group exposes more file-oriented options:

  • --media-type for upload and update

  • directory upload with --input-dir

  • regex filtering with --file-regex

  • recursive traversal with --recursive

  • generated IDs via --blob-id-prefix

Download behavior

cwms-cli blob download stores the content returned by the CDA blob endpoint.

  • Text responses are written as text.

  • Binary responses are written as bytes.

  • If the destination path has no extension, cwms-cli will try to infer one from the blob media type.

  • For text-only content without blob media handling, see clob.

Example:

cwms-cli blob download \
  --blob-id FEBRUARY_SUMMARY \
  --dest ./downloads/february-summary \
  --office SWT

Auth and scope

Blob reads can behave differently depending on whether credentials are sent.

  • If a saved login token exists, cwms-cli sends that token first.

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

  • If no token or key is available, blob read commands default to anonymous access.

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

  • If an authenticated read fails because the credential 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 credential.

Examples:

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

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

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

List pagination

cwms-cli blob list reads from the CDA blob endpoint, which defaults to a page size of 100 unless a different page_size is requested.

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

  • When --limit is set, cwms-cli also uses that value as the blob 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 blob list --office SWT --limit 250

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

Upload modes

The upload command supports two modes:

  1. Single file upload with explicit blob ID (existing behavior)

  2. Directory upload with regex matching (bulk behavior)

If you only need single-file text storage, clob is usually the simpler command group.

If you are uploading JSON and want clients to receive it with a JSON media type, blob upload --media-type application/json is usually the better fit.

Single file upload

Use --input-file and --blob-id:

cwms-cli blob upload \
  --input-file ./reports/february-summary.pdf \
  --blob-id FEBRUARY_SUMMARY \
  --office SWT

Directory upload with regex

Use --input-dir with --file-regex:

cwms-cli blob upload \
  --input-dir ./incoming \
  --file-regex '.*\.json$' \
  --office SWT

Important behavior for bulk uploads:

  • Regex is matched against each file path relative to --input-dir.

  • By default only the top level of --input-dir is scanned.

  • Add --recursive to include subdirectories.

  • Blob IDs are auto-generated from relative paths: subdir/file.json -> SUBDIR_FILE.

  • Add --blob-id-prefix to prepend text to generated IDs.

  • Uploads run one file at a time.

  • If one file fails, upload continues for remaining files.

  • Command exits non-zero if any file fails.

Bulk upload collisions

Directory upload generates blob IDs from the matched relative file paths.

  • subdir/file.json becomes SUBDIR_FILE

  • a.txt and a.json both become A

  • dir/a.txt and dir_a.txt both become DIR_A

cwms-cli now checks for these collisions before uploading anything.

  • If two or more matched files would produce the same blob ID, the command stops immediately.

  • No files are uploaded when this happens.

  • Use --blob-id-prefix only when it actually makes the generated IDs unique.

Example:

cwms-cli blob upload \
  --input-dir ./incoming \
  --file-regex '.*' \
  --blob-id-prefix OPS_ \
  --office SWT

Overwrite behavior

blob upload uses a normal Click flag pair:

  • --overwrite replaces an existing blob

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

Example:

cwms-cli blob upload \
  --input-file ./reports/february-summary.pdf \
  --blob-id FEBRUARY_SUMMARY \
  --overwrite \
  --office SWT

Regex vs shell wildcards

--file-regex expects a Python regular expression, not a shell wildcard.

  • Shell wildcard example: *.json (not valid regex for this option)

  • Regex equivalent: .*\.json$

Quote regex patterns in your terminal so the shell does not expand characters before cwms-cli receives them.

Examples:

# Match only JSON files in top-level input dir
--file-regex '.*\.json$'

# Match PDF or PNG files recursively
--recursive --file-regex '.*\.(pdf|png)$'

# Match only files under a subfolder inside input dir
--recursive --file-regex '^reports/.+\.csv$'

References:

cwms-cli blob

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

Usage

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

Example Usage:

  • Store a PDF/image as a CWMS blob with optional description

  • Download a blob by id to your local filesystem

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

  • Bulk list blobs for an office

delete

Delete a blob by ID

Usage

cwms-cli blob delete [OPTIONS]

Options

--blob-id <blob_id>

Required Blob 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 blob by ID

Usage

cwms-cli blob download [OPTIONS]

Options

--blob-id <blob_id>

Required Blob ID to download.

--dest <dest>

Destination file path. Defaults to blob-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 blobs with optional filters and sorting

Usage

cwms-cli blob list [OPTIONS]

Options

--blob-id-like <blob_id_like>

LIKE filter for blob 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 blob endpoint. Defaults to –limit if set, otherwise no pagination (all results in one page).

--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 blob by ID

Usage

cwms-cli blob update [OPTIONS]

Options

--blob-id <blob_id>

Required Blob ID to update.

--dry-run

Show request; do not send.

--description <description>

New description JSON or text.

--media-type <media_type>

New media type (guessed from file if omitted).

--input-file <input_file>

Optional file content to upload with update.

--overwrite, --no-overwrite

If true, replace existing blob.

Default:

False

-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 single file or a directory of files as CWMS blob(s).

Usage

cwms-cli blob upload [OPTIONS]

Options

--input-file <input_file>

Path to a single file to upload.

--input-dir <input_dir>

Directory containing multiple files to upload.

--file-regex <file_regex>

Regex used to match files in –input-dir (matched against relative path).

Default:

'.*'

--recursive, --no-recursive

Recurse into subdirectories when using –input-dir.

Default:

False

--blob-id <blob_id>

Blob ID to create for single-file upload.

--blob-id-prefix <blob_id_prefix>

Prefix added to generated blob IDs for directory uploads.

Default:

''

--description <description>

Optional description JSON or text.

--media-type <media_type>

Override media type (guessed from file if omitted).

--overwrite, --no-overwrite

If true, replace existing blob.

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