Update command reference for version 1.1.3

README.adoc

@@ -29,6 +29,9 @@ To learn how to update the documentation, see the https://datastax.jira.com/wiki
 The Astra CLI command reference documentation is generated from the literal CLI help text in the Astra CLI code.
 The command reference documentation should be regenerated and committed to the docs whenever a new version of the Astra CLI is released.
 
+You need a recent JDK installed.
+You do not need the Astra CLI itself installed.
+
 . If you haven't done so yet, clone the Astra CLI code repository:
 +
 [source,bash]
@@ -50,13 +53,25 @@ cd astra-cli
 git switch main && git pull
 ----
 
-. Run the following command to regenerate the command reference docs:
+. Set the path to your local clone of this documentation repository (`astra-cli-docs`):
++
+[source,bash]
+----
+ASTRA_CLI_DOCS=~/repos/astra-cli-docs
+----
+
+. Load the Astra CLI development alias:
 +
 [source,bash]
 ----
-source scripts/dev-alias.sh; astra docs && \
-    rsync -a --delete build/docs/commands/ ~/repos/astra-cli-docs/modules/commands/pages/ && \
-    cp -f build/docs/partial-nav.adoc ~/repos/astra-cli-docs/modules/commands/partials/
+source scripts/dev-alias.sh
 ----
+
+. Regenerate the command reference docs:
 +
-Replace `repos` with the appropriate path to your cloned repositories.
+[source,bash]
+----
+astra docs && \
+    rsync -a --delete build/docs/commands/ $ASTRA_CLI_DOCS/modules/commands/pages/ && \
+    cp -f build/docs/partial-nav.adoc $ASTRA_CLI_DOCS/modules/commands/partials/
+----

modules/commands/pages/astra-completions.adoc

@@ -2,7 +2,8 @@
 
 [source,shell]
 ----
-astra completions [-n=<$cliName>]
+astra completions [-qV] [--no-input] [--[no-]spinner] [--color[=WHEN]]
+                  [--dump-logs[=FILE]] [-h[=all]] [-n=<$cliName>] [-o=FORMAT]
 
 ----
 
@@ -20,8 +21,20 @@ See the help for the ``astra shellenv`` command to setup completions in your she
 
 `-n`, `--cli-name`:: CLI name to use in the completion script
 
+=== Common Options
+`-h`, `--help`:: Show this help message and exit.
+`-o`, `--output`:: One of: human, json, csv
+`-V`, `--verbose`:: Enable verbose logging output
+`-q`, `--quiet`:: Only output essential information
+`--spinner`:: Enable/disable loading spinners
+`--no-input`:: Don't ask for user input (e.g. confirmation prompts)
+`--color`:: One of: auto, never, always
+`--dump-logs`:: Write all logs to an optionally specified file
+
+
 
 == Examples
+
 [source,bash]
 ----
 # Put this in your shell profile (e.g. ``~/.zprofile``) to generate completions and set your PATH

modules/commands/pages/astra-config-create.adoc

@@ -2,9 +2,10 @@
 
 [source,shell]
 ----
-astra config create [-dqV] [--no-input] [--[no-]overwrite] [--[no-]spinner]
-                    [--color[=WHEN]] [--dump-logs[=FILE]] [-cf=PATH] [-e=ENV]
-                    [-o=FORMAT] -t=TOKEN [NAME]
+astra config create [-dqV] [--no-input] [--[no-]overwrite] [--[no-]spinner] [--
+                    [no-]validate] [--color[=WHEN]] [--dump-logs[=FILE]] [-h
+                    [=all]] [-cf=PATH] [-e=ENV] [--local-endpoint=URL]
+                    [-o=FORMAT] [-t=TOKEN] [NAME]
 
 ----
 
@@ -22,24 +23,26 @@ Use the ``--token @<file>`` syntax to securely read the token from a file, witho
 `NAME`:: Unique name for the profile
 `-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved.
 `-t`, `--token`:: Astra token (``AstraCS:...``) or ``@<file>`` to read from file
-`-e`, `--env`:: Astra environment the token belongs to: prod (default), dev, or test. Leave unset unless you were issued a non-prod token.
+`-e`, `--env`:: Astra environment the token belongs to: prod (default), dev, test, or local. Leave unset unless you were issued a non-prod token.
+`--local-endpoint`:: The endpoint URL for local Astra environments (required when --env local)
 `-d`, `--default`:: Set the created profile as the default profile. Same as 'config use <profile>'
 `--overwrite`:: Overwrite any existing profile with the same name
+`--validate`:: Validate the token by making a request to the Astra
 
-.Common Options
-[%collapsible]
-====
+=== Common Options
+`-h`, `--help`:: Show this help message and exit.
 `-o`, `--output`:: One of: human, json, csv
 `-V`, `--verbose`:: Enable verbose logging output
 `-q`, `--quiet`:: Only output essential information
 `--spinner`:: Enable/disable loading spinners
 `--no-input`:: Don't ask for user input (e.g. confirmation prompts)
 `--color`:: One of: auto, never, always
 `--dump-logs`:: Write all logs to an optionally specified file
-====
+
 
 
 == Examples
+
 [source,bash]
 ----
 # (Recommended) Interactively create a new profile

modules/commands/pages/astra-config-delete.adoc

@@ -3,7 +3,8 @@
 [source,shell]
 ----
 astra config delete [-qV] [--if-exists] [--no-input] [--[no-]spinner] [--color
-                    [=WHEN]] [--dump-logs[=FILE]] [-cf=PATH] [-o=FORMAT] [NAME]
+                    [=WHEN]] [--dump-logs[=FILE]] [-h[=all]] [-cf=PATH]
+                    [-o=FORMAT] [NAME]
 
 ----
 
@@ -20,20 +21,20 @@ Delete an existing configuration profile.
 `-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved.
 `--if-exists`:: Do not fail if the profile does not exist
 
-.Common Options
-[%collapsible]
-====
+=== Common Options
+`-h`, `--help`:: Show this help message and exit.
 `-o`, `--output`:: One of: human, json, csv
 `-V`, `--verbose`:: Enable verbose logging output
 `-q`, `--quiet`:: Only output essential information
 `--spinner`:: Enable/disable loading spinners
 `--no-input`:: Don't ask for user input (e.g. confirmation prompts)
 `--color`:: One of: auto, never, always
 `--dump-logs`:: Write all logs to an optionally specified file
-====
+
 
 
 == Examples
+
 [source,bash]
 ----
 # Delete a profile named 'my_profile'

modules/commands/pages/astra-config-get.adoc

@@ -3,7 +3,8 @@
 [source,shell]
 ----
 astra config get [-qV] [--no-input] [--[no-]spinner] [--color[=WHEN]]
-                 [--dump-logs[=FILE]] [-cf=PATH] [-k=KEY] [-o=FORMAT] [NAME]
+                 [--dump-logs[=FILE]] [-h[=all]] [-cf=PATH] [-k=KEY]
+                 [-o=FORMAT] [NAME]
 
 ----
 
@@ -25,20 +26,20 @@ Get the configuration of a profile or a specific key.
 `-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved.
 `-k`, `--key`:: Specific configuration key to retrieve
 
-.Common Options
-[%collapsible]
-====
+=== Common Options
+`-h`, `--help`:: Show this help message and exit.
 `-o`, `--output`:: One of: human, json, csv
 `-V`, `--verbose`:: Enable verbose logging output
 `-q`, `--quiet`:: Only output essential information
 `--spinner`:: Enable/disable loading spinners
 `--no-input`:: Don't ask for user input (e.g. confirmation prompts)
 `--color`:: One of: auto, never, always
 `--dump-logs`:: Write all logs to an optionally specified file
-====
+
 
 
 == Examples
+
 [source,bash]
 ----
 # Get the configuration of a specific profile

modules/commands/pages/astra-config-home-path.adoc

@@ -3,7 +3,7 @@
 [source,shell]
 ----
 astra config home path [-qV] [--no-input] [--[no-]spinner] [--color[=WHEN]]
-                       [--dump-logs[=FILE]] [-o=FORMAT] [-p | -i]
+                       [--dump-logs[=FILE]] [-h[=all]] [-o=FORMAT] [-p | -i]
 
 ----
 
@@ -29,20 +29,20 @@ By default, shows informational output when running in a TTY (interactive termin
 `-p`, `--plain`:: Print only the path to the home folder, without additional information (always)
 `-i`, `--info`:: Print informational output with context about the path (always)
 
-.Common Options
-[%collapsible]
-====
+=== Common Options
+`-h`, `--help`:: Show this help message and exit.
 `-o`, `--output`:: One of: human, json, csv
 `-V`, `--verbose`:: Enable verbose logging output
 `-q`, `--quiet`:: Only output essential information
 `--spinner`:: Enable/disable loading spinners
 `--no-input`:: Don't ask for user input (e.g. confirmation prompts)
 `--color`:: One of: auto, never, always
 `--dump-logs`:: Write all logs to an optionally specified file
-====
+
 
 
 == Examples
+
 [source,bash]
 ----
 # Get information about the path to the astra home folder

modules/commands/pages/astra-config-home.adoc

@@ -2,7 +2,8 @@
 
 [source,shell]
 ----
-astra config home [COMMAND]
+astra config home [-qV] [--no-input] [--[no-]spinner] [--color[=WHEN]]
+                  [--dump-logs[=FILE]] [-h[=all]] [-o=FORMAT] [COMMAND]
 
 ----
 
@@ -19,8 +20,20 @@ All things related to the Astra CLI home folder
 == Options
 
 
+=== Common Options
+`-h`, `--help`:: Show this help message and exit.
+`-o`, `--output`:: One of: human, json, csv
+`-V`, `--verbose`:: Enable verbose logging output
+`-q`, `--quiet`:: Only output essential information
+`--spinner`:: Enable/disable loading spinners
+`--no-input`:: Don't ask for user input (e.g. confirmation prompts)
+`--color`:: One of: auto, never, always
+`--dump-logs`:: Write all logs to an optionally specified file
+
+
 
 == Examples
+
 [source,bash]
 ----
 

modules/commands/pages/astra-config-list.adoc

@@ -3,7 +3,8 @@
 [source,shell]
 ----
 astra config list [-qV] [--no-input] [--[no-]spinner] [--color[=WHEN]]
-                  [--dump-logs[=FILE]] [-cf=PATH] [-e=ENV] [-o=FORMAT]
+                  [--dump-logs[=FILE]] [-h[=all]] [-cf=PATH] [-e=ENV]
+                  [-o=FORMAT]
 
 ----
 
@@ -20,22 +21,22 @@ List your Astra CLI configurations.
 == Options
 
 `-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved.
-`-e`, `--env`:: Filter by Astra environment
+`-e`, `--env`:: Filter by Astra environment (one of prod|test|dev|local)
 
-.Common Options
-[%collapsible]
-====
+=== Common Options
+`-h`, `--help`:: Show this help message and exit.
 `-o`, `--output`:: One of: human, json, csv
 `-V`, `--verbose`:: Enable verbose logging output
 `-q`, `--quiet`:: Only output essential information
 `--spinner`:: Enable/disable loading spinners
 `--no-input`:: Don't ask for user input (e.g. confirmation prompts)
 `--color`:: One of: auto, never, always
 `--dump-logs`:: Write all logs to an optionally specified file
-====
+
 
 
 == Examples
+
 [source,bash]
 ----
 # List your Astra CLI configurations.

modules/commands/pages/astra-config-path.adoc

@@ -3,7 +3,7 @@
 [source,shell]
 ----
 astra config path [-qV] [--no-input] [--[no-]spinner] [--color[=WHEN]]
-                  [--dump-logs[=FILE]] [-o=FORMAT] [-p | -i]
+                  [--dump-logs[=FILE]] [-h[=all]] [-o=FORMAT] [-p | -i]
 
 ----
 
@@ -29,20 +29,20 @@ By default, shows informational output when running in a TTY (interactive termin
 `-p`, `--plain`:: Print only the path to the .astrarc file, without additional information (always)
 `-i`, `--info`:: Print informational output with context about the path (always)
 
-.Common Options
-[%collapsible]
-====
+=== Common Options
+`-h`, `--help`:: Show this help message and exit.
 `-o`, `--output`:: One of: human, json, csv
 `-V`, `--verbose`:: Enable verbose logging output
 `-q`, `--quiet`:: Only output essential information
 `--spinner`:: Enable/disable loading spinners
 `--no-input`:: Don't ask for user input (e.g. confirmation prompts)
 `--color`:: One of: auto, never, always
 `--dump-logs`:: Write all logs to an optionally specified file
-====
+
 
 
 == Examples
+
 [source,bash]
 ----
 # Get information about the path to the .astrarc file

modules/commands/pages/astra-config-rename.adoc

@@ -3,7 +3,8 @@
 [source,shell]
 ----
 astra config rename [-qV] [--no-input] [--[no-]spinner] [--color[=WHEN]]
-                    [--dump-logs[=FILE]] [-cf=PATH] [-o=FORMAT] [NAME] NAME
+                    [--dump-logs[=FILE]] [-h[=all]] [-cf=PATH] [-o=FORMAT]
+                    [NAME] NAME
 
 ----
 
@@ -20,20 +21,20 @@ Rename an existing configuration profile.
 `NAME`:: New name for the profile
 `-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved.
 
-.Common Options
-[%collapsible]
-====
+=== Common Options
+`-h`, `--help`:: Show this help message and exit.
 `-o`, `--output`:: One of: human, json, csv
 `-V`, `--verbose`:: Enable verbose logging output
 `-q`, `--quiet`:: Only output essential information
 `--spinner`:: Enable/disable loading spinners
 `--no-input`:: Don't ask for user input (e.g. confirmation prompts)
 `--color`:: One of: auto, never, always
 `--dump-logs`:: Write all logs to an optionally specified file
-====
+
 
 
 == Examples
+
 [source,bash]
 ----
 # Rename a profile from 'old_name' to 'new_name'

modules/commands/pages/astra-config-use.adoc

@@ -3,7 +3,7 @@
 [source,shell]
 ----
 astra config use [-qV] [--no-input] [--[no-]spinner] [--color[=WHEN]]
-                 [--dump-logs[=FILE]] [-cf=PATH] [-o=FORMAT] [NAME]
+                 [--dump-logs[=FILE]] [-h[=all]] [-cf=PATH] [-o=FORMAT] [NAME]
 
 ----
 
@@ -19,20 +19,20 @@ Sets an existing profile to be used as the default for all commands. Use the ``-
 `NAME`:: Profile to set as default
 `-cf`, `--config-file`:: The .astrarc file to work with. See ``astra config path -h`` for how this is resolved.
 
-.Common Options
-[%collapsible]
-====
+=== Common Options
+`-h`, `--help`:: Show this help message and exit.
 `-o`, `--output`:: One of: human, json, csv
 `-V`, `--verbose`:: Enable verbose logging output
 `-q`, `--quiet`:: Only output essential information
 `--spinner`:: Enable/disable loading spinners
 `--no-input`:: Don't ask for user input (e.g. confirmation prompts)
 `--color`:: One of: auto, never, always
 `--dump-logs`:: Write all logs to an optionally specified file
-====
+
 
 
 == Examples
+
 [source,bash]
 ----
 # Set an existing profile as the default