diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index e42a432..9cd3302 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -2,6 +2,7 @@ * xref:install.adoc[] * xref:manage-cli.adoc[] * xref:upgrade.adoc[] +* xref:upgrade-pre-1.0.adoc[] * xref:uninstall.adoc[] .Quickstarts diff --git a/modules/ROOT/pages/manage-cli.adoc b/modules/ROOT/pages/manage-cli.adoc index e20a54d..a10a280 100644 --- a/modules/ROOT/pages/manage-cli.adoc +++ b/modules/ROOT/pages/manage-cli.adoc @@ -544,29 +544,250 @@ The {product} stores installation and configuration files in the following locat [cols="1h,2"] |=== -|File / Directory |Description +|File / Folder |Description |`.astra` -a|The `ASTRA_HOME` directory. +a|The {product} home folder (`ASTRA_HOME`). -_Default location_: `~/.astra` (macOS and Linux), `%USERPROFILE%\.astra` (Windows) +_Default location_: -The {product} stores the following items in this directory: +* macOS and Linux: `~/.astra` +* Windows: `%USERPROFILE%\.astra` +* All platforms: If the `XDG_DATA_HOME` environment variable is set, then the default location is `$XDG_DATA_HOME/astra`. -* The {product} executable (scripted installations only) -* Accessory executables downloaded by certain commands, such as `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]` -* {scb-brief}s +The {product} home folder contains the following items: + +* The `astra` executable (scripted installations only) +* Accessory executables that are downloaded by certain commands, such as `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]` +* xref:astra-db-serverless:databases:secure-connect-bundle.adoc[{scb-brief}s] * Cache files for <> * Logs -For more information about the `ASTRA_HOME` directory, see the {product} https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[README]. +For more information about `ASTRA_HOME`, see the https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[{product} README]. |`.astrarc` -|The {product} configuration file. +a|The {product} configuration file. + +_Default location_: -_Default location_: `~/.astrarc` (macOS and Linux), `%USERPROFILE%\.astrarc` (Windows) +* macOS and Linux: `~/.astrarc` +* Windows: `%USERPROFILE%\.astrarc` +* All platforms: If the `XDG_CONFIG_HOME` environment variable is set, then the default location is `$XDG_CONFIG_HOME/astra/.astrarc`. -This file stores your <> and their associated application tokens. +The {product} uses this file to store your <> and their associated application tokens. -For more information about the {product} configuration file, see the {product} https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[README]. +For more information about the {product} configuration file, see the https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[{product} README]. |=== + +=== Override the default home folder location + +You can override the default location of the {product} home folder (`.astra`) by setting the `ASTRA_HOME` environment variable. + +[tabs] +====== +Set the environment variable dynamically:: ++ +-- +Add the following line to your shell profile: + +[source,bash,subs="+quotes"] +---- +eval "$(astra shellenv --home "**HOME_FOLDER_PATH**")" +---- + +Replace `**HOME_FOLDER_PATH**` with the full path to your preferred {product} home folder. +-- + +Set the environment variable directly:: ++ +-- +Add the following line to your shell profile: + +[source,bash,subs="+quotes"] +---- +export ASTRA_HOME=**HOME_FOLDER_PATH** +---- + +Replace `**HOME_FOLDER_PATH**` with the full path to your preferred {product} home folder. +-- +====== + +=== Override the default configuration file location + +You can override the default location of the {product} configuration file (`.astrarc`) by setting the `ASTRA_CONFIG_FILE` environment variable. + +[tabs] +====== +Set the environment variable dynamically:: ++ +-- +Add the following line to your shell profile: + +[source,bash,subs="+quotes"] +---- +eval "$(astra shellenv --rc "**CONFIG_FILE_PATH**/.astrarc")" +---- + +Replace `**CONFIG_FILE_PATH**` with the full path to your preferred `.astrarc` configuration file. +-- + +Set the environment variable directly:: ++ +-- +Add the following line to your shell profile: + +[source,bash,subs="+quotes"] +---- +export ASTRARC=**CONFIG_FILE_PATH**/.astrarc +---- + +Replace `**CONFIG_FILE_PATH**` with the full path to your preferred `.astrarc` configuration file. +-- +====== + +[#command-output] +== Command output formats and exit codes + +Most commands support the `-o` / `--output` option to specify the format of the command output: + +[source,shell,subs="+quotes"] +---- +astra COMMAND -o **FORMAT** +---- + +The following output formats are available: + +* `human` (default): Human-readable format, optimized for command-line readability. +* `json`: Structured JSON format, suitable for programmatic parsing. +* `csv`: Comma-separated output format, ideal for data export and analysis. + +[tabs] +====== +Human-readable:: ++ +-- +The human-readable format uses tables, lists, and other visual elements to present information on the command line. +-- + +JSON:: ++ +-- +Every command supporting JSON output will always return a response of exactly this schema: + +.JSON output schema +[source,json] +---- +{ + "code": "OK" | "UNCAUGHT" | "DATABASE_NOT_FOUND" | "...", + "message": "Optional human-readable description", + "data": { + // Command-specific payload, may be an object, array, or primitive + }, + "nextSteps": [ + { + "command": "astra ...", + "comment": "Explanation of why/when to run this next" + } + ] +} +---- + +All field names in the JSON output are in camel case (`fieldName`). + +[cols="1,1,2"] +|=== +|Name |Type |Summary + +|`code` +|`string` +a|A string enum representing the exit code of the command. + +Common values include: + +* `OK`: command succeeded +* `UNCAUGHT`: unexpected failure +* `DATABASE_NOT_FOUND`: referenced resource missing +* Other command-specific codes + +|`message` +|`string` +|Optional. +A human-friendly message describing the result or error of the command. + +Not all commands include a message. + +|`data` +|Any (type varies by command) +|Freeform data specific to the command. +Typically an object or array, but may be a primitive value (string, number, boolean, etc.) depending on the command. + +|`nextSteps` +|`array` or `null` +a|Optional. +Only present if there are actionable next steps that you can take (it will never be an empty list). + +If present, it is an array of recommended next-step objects containing the following fields: + +* `command`: The command to run. +* `comment`: An explanation of why/when to run this next. +|=== +-- + +CSV:: ++ +-- +Every command supporting CSV output will always return an RFC-4180-compliant response of exactly this schema: + +.CSV output schema +[source,csv] +---- +code,message,data_field_1,data_field_2,... +---- + +All field names in the CSV output are in snake case (`field_name`). + +The first row is always the header, defining the column names. +Each subsequent row represents one data record from the command. + +The `code` and `message` fields may repeat for each row of data to keep the CSV schema consistent. +Values may contain commas or newlines and be wrapped in quotes to ensure RFC-4180-compliant CSV output. + +[cols="1,1,2"] +|=== +|Name |Type |Summary + +|`code` +|`string` +a|A string enum representing the exit code of the command. + +Common values include: + +* `OK`: command succeeded +* `UNCAUGHT`: unexpected failure +* `DATABASE_NOT_FOUND`: referenced resource missing +* Other command-specific codes + +If no rows are returned, you should assume an implicit `OK` code. + +|`message` +|`string` +|Optional. +A human-friendly message describing the result or error of the command. + +Not all commands include a message, and this field will be empty if there is nothing to report. + +|Additional data fields +|Any (type varies by command) +a|Command-specific fields representing the actual data returned. + +Fields may be empty if there is nothing to report. + +Column order is consistent per command. +|=== +-- +====== + +[NOTE] +==== +For commands that issue GET requests, the `json` response generally contains the raw response from the server, whereas the `human` and `csv` formats contain a simplified version of the data. +==== diff --git a/modules/ROOT/pages/uninstall.adoc b/modules/ROOT/pages/uninstall.adoc index 7a30cc4..facefdf 100644 --- a/modules/ROOT/pages/uninstall.adoc +++ b/modules/ROOT/pages/uninstall.adoc @@ -99,7 +99,7 @@ Manual removal:: rm $(astra config path -p) ---- -. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]: +. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home folder]: + [source,shell] ---- @@ -229,7 +229,7 @@ Manual removal:: rm -f $(astra config path -p) ---- -. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]: +. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home folder]: + [source,powershell] ---- @@ -251,7 +251,7 @@ For more information, see the https://learn.microsoft.com/en-us/powershell/modul Homebrew:: + -- -. Delete the {product} home directory (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`) and optionally its configuration file (`xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`): +. Delete the {product} home folder (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`) and optionally its configuration file (`xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`): + .. Run the `xref:commands:astra-nuke.adoc[]` command: + diff --git a/modules/ROOT/pages/upgrade-pre-1.0.adoc b/modules/ROOT/pages/upgrade-pre-1.0.adoc new file mode 100644 index 0000000..f961baa --- /dev/null +++ b/modules/ROOT/pages/upgrade-pre-1.0.adoc @@ -0,0 +1,60 @@ += Upgrade from pre-1.0 versions of the {product} +:navtitle: Upgrade from pre-1.0 versions + +// Author's note: Once we get further away from the 1.0 release, we can probably move the content of this page into a section of on the main upgrade.adoc page. + +{product} 1.0 and later do not support xref:ROOT:upgrade.adoc[in-place upgrades] from versions earlier than 1.0. + +If you have an earlier version installed, you must delete the `astra` executable before you can install the latest version: + +[tabs,sync-group-id=platforms] +====== +macOS and Linux:: ++ +-- +[source,shell] +---- +rm ~/.astra/cli/astra +---- + +.Delete custom installation +[%collapsible] +==== +If you installed the {product} to a custom location, you can use the following command to delete the `astra` executable if it exists in your PATH: + +[source,shell] +---- +rm $(which astra) +---- +==== + +This command does not delete your xref:ROOT:manage-cli.adoc#file-locations[{product} home folder and configuration file] (`.astra` and `.astrarc`). +Leave these files in place so that the new version of the {product} can continue to connect using your existing configuration. +-- + +Homebrew:: ++ +-- +[source,shell] +---- +brew uninstall datastax/astra-cli/astra-cli +---- + +Uninstalling with Homebrew does not delete your xref:ROOT:manage-cli.adoc#file-locations[{product} home folder and configuration file] (`.astra` and `.astrarc`). +Leave these files in place so that the new version of the {product} can continue to connect using your existing configuration. +-- +====== + +After you delete the old `astra` executable, follow the instructions in xref:ROOT:install.adoc[] to install the latest version. + +.Breaking changes in version 1.0 +[IMPORTANT] +==== +{product} version 1.0 is largely backwards-compatible with pre-1.0 versions. +However, there are some changes that might break certain scripted usage, such as: + +* New standardized xref:ROOT:manage-cli.adoc#output-formats[JSON and CSV output formats and exit codes]. + +* Minor command and flag name changes. +For a full list of name changes, see the https://github.com/datastax/astra-cli?tab=readme-ov-file#whats-changed[release notes]. +==== diff --git a/modules/ROOT/pages/upgrade.adoc b/modules/ROOT/pages/upgrade.adoc index fc2bb57..ad4cb20 100644 --- a/modules/ROOT/pages/upgrade.adoc +++ b/modules/ROOT/pages/upgrade.adoc @@ -3,6 +3,8 @@ Keep the {product} up to date to access new features, improvements, and security updates. +If you're upgrading from version 0.6 or earlier, see xref:ROOT:upgrade-pre-1.0.adoc[]. + [IMPORTANT] ==== If you used a package manager to install the {product}, such as Homebrew, then you must use the same package manager to upgrade the {product}.