Merge branch 'main' into carl/feedback-1b--login-command-ergonomics

Author: carl-adams-planet

src/planet_auth_utils/commands/cli/main.py

@@ -185,9 +185,12 @@ def cmd_plauth_login(
     yes,
 ):
     """
-    Perform an initial login, obtain user authorization, and save access
-    tokens for the selected authentication profile.  The specific process
-    used depends on the selected options and authentication profile.
+    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.
     """
     extra = {}
     if project:

src/planet_auth_utils/commands/cli/oauth_cmd.py

@@ -164,6 +164,8 @@ def cmd_oauth_refresh(ctx, scope):
     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.
     """
     _check_auth_client_type_for_click_ctx(ctx)
     saved_token = FileBackedOidcCredential(None, ctx.obj["AUTH"].token_file_path())
@@ -376,7 +378,8 @@ def cmd_oauth_revoke_refresh_token(ctx):
 @recast_exceptions_to_click(AuthException, FileNotFoundError)
 def cmd_oauth_userinfo(ctx):
     """
-    Look up user information from the auth server using the access token.
+    Look up user information for the current user.  Look up is performed by
+    querying the authorization server using the current access token.
     """
     _check_auth_client_type_for_click_ctx(ctx)
     saved_token = FileBackedOidcCredential(None, ctx.obj["AUTH"].token_file_path())
@@ -395,6 +398,7 @@ def cmd_oauth_userinfo(ctx):
 def cmd_oauth_print_access_token(ctx, refresh):
     """
     Show the current OAuth access token.  Stale tokens will be automatically refreshed.
+    This command only applies to auth profiles that use OAuth access tokens.
     """
     _check_auth_client_type_for_click_ctx(ctx)
     saved_token = FileBackedOidcCredential(None, ctx.obj["AUTH"].token_file_path())
@@ -428,8 +432,8 @@ def cmd_oauth_print_access_token(ctx, refresh):
 @recast_exceptions_to_click(AuthException, FileNotFoundError)
 def cmd_oauth_decode_jwt_access_token(ctx, human_readable):
     """
-    Decode a JWT access token locally and display its contents.  NO
-    VALIDATION IS PERFORMED.  This function is intended for local
+    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.
@@ -445,8 +449,8 @@ def cmd_oauth_decode_jwt_access_token(ctx, human_readable):
 @recast_exceptions_to_click(AuthException, FileNotFoundError)
 def cmd_oauth_decode_jwt_id_token(ctx, human_readable):
     """
-    Decode a JWT ID token locally and display its contents.  NO
-    VALIDATION IS PERFORMED.  This function is intended for local
+    Decode a JWT ID token locally.
+    NO VALIDATION IS PERFORMED.  This function is intended for local
     debugging purposes.
     """
     _check_auth_client_type_for_click_ctx(ctx)
@@ -460,8 +464,8 @@ def cmd_oauth_decode_jwt_id_token(ctx, human_readable):
 @recast_exceptions_to_click(AuthException, FileNotFoundError)
 def cmd_oauth_decode_jwt_refresh_token(ctx, human_readable):
     """
-    Decode a JWT refresh token locally and display its contents.  NO
-    VALIDATION IS PERFORMED.  This function is intended for local
+    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.

src/planet_auth_utils/commands/cli/planet_legacy_auth_cmd.py

@@ -121,7 +121,8 @@ def cmd_pllegacy_login(ctx, auth_profile, username, password, sops, yes):
 @recast_exceptions_to_click(AuthException, FileNotFoundError)
 def cmd_pllegacy_print_api_key(ctx):
     """
-    Show the API Key used by the currently selected authentication profile.
+    Show the current API Key.  This command only applies to auth profiles
+    that use simple API keys.
     """
     # We also support StaticApiKeyAuthClient in some cases where the user
     # directly provides an API key.  Such clients can use the legacy API
@@ -151,7 +152,7 @@ def cmd_pllegacy_print_api_key(ctx):
 @recast_exceptions_to_click(AuthException, FileNotFoundError)
 def cmd_pllegacy_print_access_token(ctx):
     """
-    Show the legacy JWT currently held by the selected authentication profile.
+    Show the current legacy JWT access token.
     """
     _check_client_type_pllegacy_for_click_ctx(ctx)
     saved_token = FileBackedPlanetLegacyApiKey(api_key_file=ctx.obj["AUTH"].token_file_path())

src/planet_auth_utils/commands/cli/profile_cmd.py

@@ -271,7 +271,9 @@ def cmd_profile_copy(sops, src, dst):
 @recast_exceptions_to_click(AuthException, FileNotFoundError, PermissionError)
 def cmd_profile_set(selected_profile):
     """
-    Configure the default authentication profile to use when one is not otherwise specified.
+    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.
     """
     if not selected_profile:
         selected_profile = _dialogue_choose_auth_profile()