CLI Reference
plauth
Planet authentication utility
Usage:
plauth [OPTIONS] COMMAND [ARGS]...
Options:
-l, --loglevel [critical|error|warning|info|debug]
Set the log level. [env var: PL_LOGLEVEL;
default: INFO]
--auth-profile TEXT Select the client authentication profile to
use. [env var: PL_AUTH_PROFILE]
--help Show this message and exit.
jwt
JWT utility for working with tokens. These functions are primarily targeted towards debugging usage. Many of the functions do not perform token validation. THE CONTENTS OF UNVALIDATED TOKENS MUST BE TREATED AS UNTRUSTED AND POTENTIALLY MALICIOUS.
Usage:
plauth jwt [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
decode
Decode a JWT token WITHOUT PERFORMING ANY VALIDATION.
Usage:
plauth jwt decode [OPTIONS]
Options:
-H, --human-readable / --no-human-readable
Reformat fields to be human readable.
[default: no-human-readable]
--token TEXT Token string.
--token-file PATH File containing a token.
--help Show this message and exit.
validate-oauth
Perform signature validation on an RFC 9068 compliant JWT token.
The iss and aud claims will be used to look up signing keys
using OAuth2/OIDC discovery protocols and perform basic validation
checks.
This command performs only basic signature verification and token validity
checks. For checks against auth server token revocation lists, see the oauth
command. For deeper checks specific to the claims and structure of
Identity or Access tokens, see the oauth command.
WARNING:
THIS TOOL IS ABSOLUTELY INAPPROPRIATE FOR PRODUCTION TRUST USAGE. This is a development and debugging utility. The default behavior to inspect the token for issuer and audience information used to validate the token is wholly incorrect for a production use case. The decision of which issuers to trust with what audiences MUST be controlled by the service operator.
Usage:
plauth jwt validate-oauth [OPTIONS]
Options:
-H, --human-readable / --no-human-readable
Reformat fields to be human readable.
[default: no-human-readable]
--token TEXT Token string.
--token-file PATH File containing a token.
--audience TEXT Token audiences. Specify multiple options
to set multiple audiences. When set via
environment variable, audiences should be
white space delimited. [env var:
PL_AUTH_AUDIENCE]
--issuer TEXT Token issuer. [env var: PL_AUTH_ISSUER]
--help Show this message and exit.
legacy
Planet legacy authentication commands.
Usage:
plauth legacy [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
login
Perform an initial login using Planet's legacy authentication interfaces.
Usage:
plauth legacy login [OPTIONS]
Options:
--password TEXT Password used for authentication. May not be used
by all authentication mechanisms. [env var:
PL_AUTH_PASSWORD]
--username, --email TEXT Username used for authentication. May not be used
by all authentication mechanisms. [env var:
PL_AUTH_USERNAME]
--sops / --no-sops Use sops when creating new files where applicable.
The environment must be configured for SOPS to
work by default. [default: no-sops]
-y, --yes / -n, --no Skip user prompts with a "yes" or "no" selection.
--help Show this message and exit.
print-access-token
Show the current legacy JWT access token.
Usage:
plauth legacy print-access-token [OPTIONS]
Options:
--help Show this message and exit.
print-api-key
Show the current API Key. This command only applies to auth profiles that use simple API keys.
Usage:
plauth legacy print-api-key [OPTIONS]
Options:
--help Show this message and exit.
login
Perform an initial login.
This command performs an initial login, obtains user authorization, and saves access tokens for the selected authentication profile. The specific process used depends on the selected options and authentication profile.
Usage:
plauth login [OPTIONS]
Options:
--open-browser / --no-open-browser
Allow/Suppress the automatic opening of a
browser window. [default: open-browser]
--show-qr-code / --no-show-qr-code
Control whether a QR code is displayed for
the user. [default: no-show-qr-code]
--scope TEXT Token scope. Specify multiple options to
specify multiple scopes. When set via
environment variable, scopes should be white
space delimited. Default value is
determined by the selected auth profile.
[env var: PL_AUTH_SCOPE]
--audience TEXT Token audiences. Specify multiple options
to set multiple audiences. When set via
environment variable, audiences should be
white space delimited. [env var:
PL_AUTH_AUDIENCE]
--organization TEXT Organization to use when performing
authentication. When present, this option
will be appended to authorization requests.
Not all implementations understand this
option. [env var: PL_AUTH_ORGANIZATION]
--project TEXT Project ID to use when performing
authentication. When present, this option
will be appended to authorization requests.
Not all implementations understand this
option. [env var: PL_AUTH_PROJECT]
--auth-profile TEXT Select the client authentication profile to
use. [env var: PL_AUTH_PROFILE]
--auth-client-id TEXT Specify the OAuth client ID. [env var:
PL_AUTH_CLIENT_ID]
--auth-client-secret TEXT Specify the OAuth client Secret. [env var:
PL_AUTH_CLIENT_SECRET]
--auth-api-key TEXT Specify an API key. [env var: PL_API_KEY]
--sops / --no-sops Use sops when creating new files where
applicable. The environment must be
configured for SOPS to work by default.
[default: no-sops]
-y, --yes / -n, --no Skip user prompts with a "yes" or "no"
selection.
--help Show this message and exit.
oauth
OAuth2 authentication commands.
Usage:
plauth oauth [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
decode-access-token
Decode a JWT access token locally. NO VALIDATION IS PERFORMED. This function is intended for local debugging purposes. Note: Access tokens need not be JWTs. This function will not work for authorization servers that issue access tokens in other formats.
Usage:
plauth oauth decode-access-token [OPTIONS]
Options:
-H, --human-readable / --no-human-readable
Reformat fields to be human readable.
[default: no-human-readable]
--help Show this message and exit.
decode-id-token
Decode a JWT ID token locally. NO VALIDATION IS PERFORMED. This function is intended for local debugging purposes.
Usage:
plauth oauth decode-id-token [OPTIONS]
Options:
-H, --human-readable / --no-human-readable
Reformat fields to be human readable.
[default: no-human-readable]
--help Show this message and exit.
decode-refresh-token
Decode a JWT refresh token locally. NO VALIDATION IS PERFORMED. This function is intended for local debugging purposes. Note: Refresh tokens need not be JWTs. This function will not work for authorization servers that issue refresh tokens in other formats.
Usage:
plauth oauth decode-refresh-token [OPTIONS]
Options:
-H, --human-readable / --no-human-readable
Reformat fields to be human readable.
[default: no-human-readable]
--help Show this message and exit.
discovery
Look up OAuth server discovery information.
Usage:
plauth oauth discovery [OPTIONS]
Options:
--help Show this message and exit.
list-scopes
List available OAuth scopes.
This command will query the auth server for available scopes that may be requested.
Usage:
plauth oauth list-scopes [OPTIONS]
Options:
--help Show this message and exit.
login
Perform an initial login using OAuth.
Usage:
plauth oauth login [OPTIONS]
Options:
--open-browser / --no-open-browser
Allow/Suppress the automatic opening of a
browser window. [default: open-browser]
--show-qr-code / --no-show-qr-code
Control whether a QR code is displayed for
the user. [default: no-show-qr-code]
--scope TEXT Token scope. Specify multiple options to
specify multiple scopes. When set via
environment variable, scopes should be white
space delimited. Default value is
determined by the selected auth profile.
[env var: PL_AUTH_SCOPE]
--audience TEXT Token audiences. Specify multiple options
to set multiple audiences. When set via
environment variable, audiences should be
white space delimited. [env var:
PL_AUTH_AUDIENCE]
--organization TEXT Organization to use when performing
authentication. When present, this option
will be appended to authorization requests.
Not all implementations understand this
option. [env var: PL_AUTH_ORGANIZATION]
--project TEXT Project ID to use when performing
authentication. When present, this option
will be appended to authorization requests.
Not all implementations understand this
option. [env var: PL_AUTH_PROJECT]
--auth-client-id TEXT Specify the OAuth client ID. [env var:
PL_AUTH_CLIENT_ID]
--auth-client-secret TEXT Specify the OAuth client Secret. [env var:
PL_AUTH_CLIENT_SECRET]
--sops / --no-sops Use sops when creating new files where
applicable. The environment must be
configured for SOPS to work by default.
[default: no-sops]
-y, --yes / -n, --no Skip user prompts with a "yes" or "no"
selection.
-O, --extra TEXT Specify an extra option. Specify multiple
options to specify multiple extra options.
The format of an option is <key>=<value>.
When set via environment variable, values
should be delimited by whitespace. [env
var: PL_AUTH_EXTRA]
--help Show this message and exit.
print-access-token
Show the current OAuth access token. Stale tokens will be automatically refreshed. This command only applies to auth profiles that use OAuth access tokens.
Usage:
plauth oauth print-access-token [OPTIONS]
Options:
--refresh / --no-refresh Automatically perform a credential refresh if
required. [default: refresh]
--help Show this message and exit.
refresh
Obtain a new credential using the saved refresh token.
It is possible to request a refresh token with scopes that are different from what is currently possessed, but you will never be granted more scopes than what the user has authorized.
This command only applies to auth profiles that use OAuth access tokens.
Usage:
plauth oauth refresh [OPTIONS]
Options:
--scope TEXT Token scope. Specify multiple options to specify multiple
scopes. When set via environment variable, scopes should be
white space delimited. Default value is determined by the
selected auth profile. [env var: PL_AUTH_SCOPE]
--help Show this message and exit.
revoke-access-token
Revoke the current access token.
Revoking the access token does not revoke the refresh token, which will remain powerful.
It should be noted that while this command revokes the access token with the auth services, access tokens are bearer tokens, and may still be accepted by some service endpoints. It is up to each service whether access tokens are accepted as bearer tokens, or double verified against the auth services.
Usage:
plauth oauth revoke-access-token [OPTIONS]
Options:
--help Show this message and exit.
revoke-refresh-token
Revoke the current refresh token.
After the refresh token has been revoked, it will be necessary to login again to access other services. Revoking the refresh token does not revoke the current access token, which may remain potent until its natural expiration time if not also revoked.
Usage:
plauth oauth revoke-refresh-token [OPTIONS]
Options:
--help Show this message and exit.
userinfo
Look up user information for the current user. Look up is performed by querying the authorization server using the current access token.
Usage:
plauth oauth userinfo [OPTIONS]
Options:
--help Show this message and exit.
validate-access-token
Validate the access token. Validation is performed by calling out to the auth provider's token introspection network service.
Usage:
plauth oauth validate-access-token [OPTIONS]
Options:
-H, --human-readable / --no-human-readable
Reformat fields to be human readable.
[default: no-human-readable]
--help Show this message and exit.
validate-access-token-local
Validate the access token locally.
When scopes are passed to the access token validator, the validator performs an "any of" check. It will assert that any one of the scopes is present in the token. The validator does not assert that all scopes are present.
It no scopes are passed to the validator, none are required.
NOTICE: This functionality is not supported for all OAuth implementations. Access tokens are intended for consumption by resource servers, and may be opaque to the client.
Usage:
plauth oauth validate-access-token-local [OPTIONS]
Options:
--audience TEXT Token audiences. Specify multiple options
to set multiple audiences. When set via
environment variable, audiences should be
white space delimited. [env var:
PL_AUTH_AUDIENCE]
--scope TEXT Token scope. Specify multiple options to
specify multiple scopes. When set via
environment variable, scopes should be white
space delimited. Default value is
determined by the selected auth profile.
[env var: PL_AUTH_SCOPE]
-H, --human-readable / --no-human-readable
Reformat fields to be human readable.
[default: no-human-readable]
--help Show this message and exit.
validate-id-token
Validate the ID token. Validation is performed by calling out to the auth provider's token introspection network service.
Usage:
plauth oauth validate-id-token [OPTIONS]
Options:
-H, --human-readable / --no-human-readable
Reformat fields to be human readable.
[default: no-human-readable]
--help Show this message and exit.
validate-id-token-local
Validate the ID token. This command validates the ID token locally, checking the token signature and claims against expected values. While validation is performed locally, network access is still required to obtain the signing keys from the auth provider.
Usage:
plauth oauth validate-id-token-local [OPTIONS]
Options:
-H, --human-readable / --no-human-readable
Reformat fields to be human readable.
[default: no-human-readable]
--help Show this message and exit.
validate-refresh-token
Validate the refresh token. Validation is performed by calling out to the auth provider's token introspection network service.
Usage:
plauth oauth validate-refresh-token [OPTIONS]
Options:
-H, --human-readable / --no-human-readable
Reformat fields to be human readable.
[default: no-human-readable]
--help Show this message and exit.
profile
Manage auth profiles.
Usage:
plauth profile [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
copy
Copy an existing profile to create a new profile. Only the persistent profile configuration will be copied. User access tokens initialized via a call to login will not be copied.
Usage:
plauth profile copy [OPTIONS] SRC DST
Options:
--sops / --no-sops Use sops when creating new files where applicable. The
environment must be configured for SOPS to work by
default. [default: no-sops]
--help Show this message and exit.
create
Wizard to create a new authentication profile.
Usage:
plauth profile create [OPTIONS] [NEW_PROFILE_NAME]
Options:
--sops / --no-sops Use sops when creating new files where applicable. The
environment must be configured for SOPS to work by
default. [default: no-sops]
--help Show this message and exit.
edit
Edit an existing profile.
Usage:
plauth profile edit [OPTIONS]
Options:
--help Show this message and exit.
list
List auth profiles.
Usage:
plauth profile list [OPTIONS]
Options:
-l, --long Longer, more detailed output.
--help Show this message and exit.
set
Configure the default authentication profile. Preference will be saved to disk and will be used when one is not otherwise specified. Command line options and environment variables override on-disk preferences.
Usage:
plauth profile set [OPTIONS] [SELECTED_PROFILE]
Options:
--help Show this message and exit.
show
Show the current authentication profiles.
Usage:
plauth profile show [OPTIONS]
Options:
--help Show this message and exit.
reset
Reset saved auth state.
Old auth state is not deleted. It is moved aside and preserved.
Usage:
plauth reset [OPTIONS]
Options:
--help Show this message and exit.
version
Show the version of planet auth components.
Usage:
plauth version [OPTIONS]
Options:
--help Show this message and exit.