Update help text and error messages for `--env` option

[eric-schneider]

Background

The Astra CLI supports a -e/--env option on most commands that can be passed in tandem with the -t/--token option. The -e/--env option lets you specify which Astra environment the token should be validated against. The default is prod, and the -e/--env option lets you specify dev or test.

However, the only environment that Astra customers ever get access to is prod. The dev and test environments are internal to IBM. If the application token was generated for a database/organization in dev or test, then you must pass the -e/--env option at the same time you pass the -t/--token option, otherwise the Astra CLI defaults to validating the token against prod (the default) and the validation will fail.

Issue

Given that Astra customers only have access to prod and would never have use for the -e/--env option, the current help text and error messages can be confusing to public users of the Astra CLI.

Proposed solution

Update the help text and error messages to something like the following:

Pattern 1 — token-paired (db get, db create, etc.)

Current: --env:: Override the target astra environment

Recommended: --env:: Astra environment the token belongs to: prod (default), dev, or test. Leave unset unless you were issued a non-prod token.

Pattern 2 — config create

Current: -e, --env:: Astra environment the token targets

Recommended: -e, --env:: Astra environment the token belongs to: prod (default), dev, or test. Leave unset unless you were issued a non-prod token.

Pattern 3 — config list / config (the filter)

Current: -e, --env:: Filter by Astra environment

Recommended: -e, --env:: List only profiles for the given Astra environment: prod, dev, or test. Omit to list all profiles.

Error message

Current:

$ astra config create test -t <token> -e dev

Error: The token you provided is invalid.

The token is not a valid Astra token for the given Astra environment. It is, however, valid for prod.

If you are targeting a different environment, ensure that the right environment is set with the --env option.

Recommended:

$ astra config create test -t <token> -e dev

Error: This token isn't valid for the 'dev' environment — it's valid for 'prod'. To use it, omit '--env' ('prod' is the default) or pass '--env prod'. The 'dev' and 'test' environments are for Astra-internal use.