Login command

Use cwms-cli login to start the CWBI OIDC PKCE flow and save the resulting session for reuse. The command already has working defaults for the provider, client ID, scope, callback host, callback port, timeout, and the provider-specific token file path under ~/.config/cwms-cli/auth/.

By default, cwms-cli discovers the OIDC realm from the target CDA API’s OpenAPI spec at <api-root>/swagger-docs and caches the discovered value locally.

By default, the callback listener starts at port 5555 and automatically tries up to three subsequent ports if earlier ones are already in use.

If a browser cannot be opened automatically, the command prints the authorization URL so the user can continue manually.

Examples

  • Use the default login settings:

    cwms-cli login

  • Print the authorization URL instead of opening a browser:

    cwms-cli login --no-browser

  • Use the login.gov identity provider hint:

    cwms-cli login --provider login.gov

  • Save the session to a custom file:

    cwms-cli login --token-file ~/.config/cwms-cli/auth/custom-login.json

  • Change the local callback listener host and port:

    cwms-cli login --redirect-host 127.0.0.1 --redirect-port 6000

  • Override the client ID and scopes:

    cwms-cli login --client-id cwms --scope "openid profile"

  • Discover OIDC configuration from a different CDA target:

    cwms-cli login --api-root https://cwms-data.usace.army.mil/cwms-data

  • Wait longer for the callback during manual authentication:

    cwms-cli login --timeout 300 --no-browser

  • Use a custom CA bundle for TLS verification:

    cwms-cli login --ca-bundle /path/to/ca-bundle.pem

  • Refresh an existing saved session without opening a browser:

    cwms-cli login --refresh

cwms-cli login

Authenticate with CWBI OIDC using PKCE and save tokens for reuse.

Usage

cwms-cli login [OPTIONS]

Options

--provider <provider>

Identity provider hint to send to Keycloak.

Default:

'federation-eams'

Options:

federation-eams | login.gov

--client-id <client_id>

OIDC client ID.

Default:

'cwms'

-a, --api-root <api_root>

CDA API root used to discover the OpenID Connect configuration.

Default:

'https://cwms-data.usace.army.mil/cwms-data'

--scope <scope>

OIDC scopes to request.

Default:

'openid profile'

--redirect-host <redirect_host>

Local host for the login callback listener.

Default:

'localhost'

--redirect-port <redirect_port>

Local port for the login callback listener.

Default:

5555

--token-file <token_file>

Path to save the login session JSON. Defaults to a provider-specific file under ~/.config/cwms-cli/auth/.

--refresh

Refresh an existing saved session instead of opening a new browser login.

--no-browser

Print the authorization URL instead of trying to open a browser automatically.

--timeout <timeout>

Seconds to wait for the local login callback.

Default:

30

--ca-bundle <ca_bundle>

CA bundle to use for TLS verification.

Environment variables

CDA_API_ROOT

Provide a default for -a