Users commands

The cwms-cli users command group is the entry point for CWMS user-management operations in the CLI.

Landing page

## cwms-cli users roles.

This command lists the assignable roles returned by the CWMS Data API for the current credentials.

In practice, cwms-cli users roles and cwms.get_roles() typically return the same role catalog regardless of office. Office context still matters for actual user-role assignment work, but the role list itself is usually the same for any given office.

If the command returns a permission error, use an API key for a user with user-management admin access such as CWMS User Admins. You can alter this in server admin or by reaching out to your region’s CWMS administrator.

Examples

List the available user-management roles:

cwms-cli users roles --office SPK --api-root http://localhost:8082/cwms-data/ --api-key <ADMIN_KEY>
Use API keys from the environment instead of a command-line arguments:

cwms-cli users roles

Add a role to a user

Use cwms-cli users roles add to add one or more roles to an existing user for an office. This command maps to the CWMS user-management POST operation on /user/{user-name}/roles/{office-id}.

Before sending the request, the CLI validates that:

the target user exists in the CDA /users catalog
each requested role exists in the CDA /roles catalog

Interactive mode

Run the add command without add-specific arguments to use the interactive flow:

cwms-cli users roles add

The interactive flow will:

Ask if the office you have set is the one you want to use
let you override that office before the request is sent
prompt for the user name
show the available roles
let you enter one or more roles to add

Argument mode

If you already know the values you want, you can pass them directly:

cwms-cli users roles add --office SPK --api-root http://localhost:8082/cwms-data/ --api-key <ADMIN_KEY> --user-name q0hectest --roles "CWMS User Admins" --roles "Viewer Users"

You can also pass roles as a comma-separated list:

cwms-cli users roles add --office SPK --api-root http://localhost:8082/cwms-data/ --api-key <ADMIN_KEY> --user-name q0hectest --roles "CWMS User Admins,Viewer Users"

All-or-none add arguments

For add-specific options, provide all required values or none of them.

Delete roles from a user

Use cwms-cli users roles delete to delete one or more roles from an existing user for an office. This command maps to the CWMS user-management DELETE operation on /user/{user-name}/roles/{office-id}.

Before sending the request, the CLI validates that:

the target user exists in the CDA /users catalog
each requested role exists in the CDA /roles catalog

Interactive mode

Run the delete command without delete-specific arguments to use the interactive flow:

cwms-cli users roles delete

The interactive flow will:

ask if the office you have set is the one you want to use
let you override that office before the request is sent
prompt for the user name
show the available roles
let you enter one or more roles to delete

Argument mode

If you already know the values you want, you can pass them directly:

cwms-cli users roles delete --office SPK --api-root http://localhost:8082/cwms-data/ --api-key <ADMIN_KEY> --user-name q0hectest --roles "CWMS User Admins" --roles "Viewer Users"

You can also pass roles as a comma-separated list:

cwms-cli users roles delete --user-name q0hectest --roles "CWMS User Admins,Viewer Users"

All-or-none delete arguments

For delete-specific options, provide all required values or none of them.

See also

CLI reference

cwms-cli users

Manage CWMS users and user-management roles

Usage

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

roles

Manage CWMS users and user-management roles

Usage

cwms-cli users roles [OPTIONS] COMMAND [ARGS]...

add

Add one or more roles to an existing user

Usage

cwms-cli users roles add [OPTIONS]

Options

-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

-kl, --api-key-loc <api_key_loc>: File storing an API key. Optional when a saved cwms-cli login token is available.

-u, --user-name <user_name>: Required Existing user name.

--roles <roles>: enter admin, readonly, readwrite, or individual role name(s) to add. Repeat the option or pass a comma/pipe-separated list.

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

delete

Remove one or more roles from an existing user

Usage

cwms-cli users roles delete [OPTIONS]

Options

-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

-kl, --api-key-loc <api_key_loc>: File storing an API key. Optional when a saved cwms-cli login token is available.

-u, --user-name <user_name>: Required Existing user name.

--roles <roles>: enter ‘all’ to delete all roles, or admin, readonly, readwrite, or individual role name(s) to delete. Repeat the option or pass a comma/pipe-separated list.

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-all

List assignable CWMS user-management roles

Usage

cwms-cli users roles list-all [OPTIONS]

Options

-a, --api-root <api_root>: Required Api Root for CDA. Can be user defined or placed in a env variable CDA_API_ROOT

-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.

-kl, --api-key-loc <api_key_loc>: File storing an API key. Optional when a saved cwms-cli login token is available.

Environment variables

CDA_API_ROOT: Provide a default for -a

CDA_API_KEY: Provide a default for -k

list-user

List roles for a specific user and office

Usage

cwms-cli users roles list-user [OPTIONS]

Options

-u, --user-name <user_name>: Required Existing user name.

-o, --office <office>: Office to grab data for

-a, --api-root <api_root>: Required Api Root for CDA. Can be user defined or placed in a env variable CDA_API_ROOT

-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.

-kl, --api-key-loc <api_key_loc>: File storing an API key. Optional when a saved cwms-cli login token is available.

Environment variables

OFFICE: Provide a default for -o

CDA_API_ROOT: Provide a default for -a

CDA_API_KEY: Provide a default for -k

user-ids

List all available user IDs for an office or lookup using like filter

Usage

cwms-cli users user-ids [OPTIONS]

Options

-o, --office <office>: Office to grab data for

-a, --api-root <api_root>: Required Api Root for CDA. Can be user defined or placed in a env variable CDA_API_ROOT

-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.

-kl, --api-key-loc <api_key_loc>: File storing an API key. Optional when a saved cwms-cli login token is available.

-ul, --username-like <username_like>: Enter any part of a user name to filter user id listing. Case-insensitive.

Environment variables

OFFICE: Provide a default for -o

CDA_API_ROOT: Provide a default for -a

CDA_API_KEY: Provide a default for -k