update readme, docs, install sripts, and more

Author: toptobes

README.md

@@ -3,7 +3,9 @@
 [![License Apache2](https://img.shields.io/hexpm/l/plug.svg)](http://www.apache.org/licenses/LICENSE-2.0)
 ![Latest Release](https://img.shields.io/badge/release-1.0.0.beta-orange)
 
-Astra CLI provides a command line interface in a terminal to operate DataStax Astra. The goal is to offer access to any feature without accessing the user interface.
+Astra CLI provides a terminal interface to operate DataStax Astra. The goal is to offer access to any feature without accessing the user interface.
+
+![Astra CLI MacOS demo](assets/demo.gif)
 
 > This is the README for the new 1.0.0 (beta) version of the Astra CLI. See the README for the previous version [here](https://github.com/datastax/astra-cli/tree/0.x?tab=readme-ov-file#astra-cli).
 
@@ -18,8 +20,8 @@ Astra CLI provides a command line interface in a terminal to operate DataStax As
 - [Customization](#customization)
     - [Home folder location](#home-folder-location)
     - [`.astrarc` location](#astrarc-location)
-    - [Response format](#response-format)
-    - [Output level](#output-level)
+    - [Output format](#output-format)
+    - [Output style](#output-style)
 - [What's new](#whats-new)
     - [Windows support](#windows-support)
     - [Improved output and interactivity](#improved-output-and-interactivity)
@@ -83,7 +85,7 @@ You can also download a specific version, or the latest prerelease version, usin
 
 ```bash
 # Upgrade (or downgrade!) to a specific version
-astra upgrade --version 1.0.0-rc-2
+astra upgrade --version 1.0.0-rc.4
 
 # Upgrade to the latest prerelease version
 astra upgrade --pre
@@ -120,7 +122,7 @@ After installation, run `astra setup` to interactively set up your credentials i
 astra setup
 ```
 
-The `astra config` subcommands can be further used to manager your configuration profiles.
+The `astra config` subcommands can be further used to manage your configuration profiles.
 
 ### Using the CLI without a credentials file
 
@@ -145,18 +147,18 @@ astra db list --token <your_token> [--env <your_env>]
 
 ### Home folder location
 
-The Astra CLI uses a singular home folder to store various data, such as downloaded programs, secure connect bundles, completions caches, etc.
+The Astra CLI uses a single home folder to store various data, such as downloaded programs, secure connect bundles, completions caches, etc.
 
 By default, this folder is located at either `$XDG_DATA_HOME/astra` (if the `XDG_DATA_HOME` environment variable is set), or at `~/.astra` (if not).
 
 You can override this location by setting the `ASTRA_HOME` environment variable to your desired path.
 
 ```bash
-# Possible
-echo 'export ASTRA_HOME=/path/to/your/astra/home' >> ~/.bashrc
+# Option 1: Set the environment variable directly
+echo 'export ASTRA_HOME=/path/to/your/astra/home' >> ~/.bash_profile
 
-# Preferred
-echo 'eval "$(astra shellenv --home "/path/to/your/astra/home")"' >> ~/.bashrc
+# Option 2: Use shellenv (preferred, as it handles shell-specific setup)
+echo 'eval "$(astra shellenv --home "/path/to/your/astra/home")"' >> ~/.bash_profile
 ```
 
 ### `.astrarc` location
@@ -168,11 +170,11 @@ By default, this file is located at either `$XDG_CONFIG_HOME/astra/.astrarc` (if
 You can override this location by setting the `ASTRARC` environment variable to your desired path.
 
 ```bash
-# Possible
-echo 'export ASTRARC=/path/to/your/.astrarc' >> ~/.bashrc
+# Option 1: Set the environment variable directly
+echo 'export ASTRARC=/path/to/your/.astrarc' >> ~/.bash_profile
 
-# Preferred
-echo 'eval "$(astra shellenv --rc "/path/to/your/.astrarc")"' >> ~/.bashrc
+# Option 2: Use shellenv (preferred, as it handles shell-specific setup)
+echo 'eval "$(astra shellenv --rc "/path/to/your/.astrarc")"' >> ~/.bash_profile
 ```
 
 ### Output format
@@ -565,6 +567,14 @@ Some commands, namely the ones that build on `cqlsh`, `dsbulk`, and `pulsar-shel
 
 <details>
   <summary><strong>pulsar-shell</strong></summary>
+
+  Similar to `cqlsh` and `dsbulk`, the pulsar-shell commands have been organized under the `astra streaming pulsar` subcommand.
+
+  The available commands include:
+  - `astra streaming pulsar shell` – Launch an interactive Apache Pulsar shell session for a streaming tenant
+    - Supports `-e <statement>` and `-f <file>` flags for non-interactive execution
+  - `astra streaming pulsar version` – Prints the version of `pulsar-shell` that is used by the CLI
+  - `astra streaming pulsar path` – Prints the path to the `pulsar-shell` binary, installing it if necessary
 </details>
 
 ### XDG spec compliance
@@ -575,18 +585,63 @@ The Astra CLI will now respect the `$XDG_DATA_HOME` and `$XDG_CONFIG_HOME` envir
 
 <details>
   <summary>Other minor changes (not exhaustive)</summary>
-    <li> automatically patch cqlsh script to work on machines with a newer python version as default by testing for older python versions explicitly
-    <li> consistent support of the `--output` flag across all commands–either a format is supported, or the command will error out before doing anything
-    <li> removed `astra-init` script in favor of the `astra compgen` command
-    <li> removed `astra login` since it was just an alias of `astra setup`
-    <li> `setup` command has been completely rewritten and improved to be much more interactive and user-friendly
-    <li> fewer API calls will be made due to better internal caching and logic (commands may be much faster now!)
-    <li> fixed inconsistent shell coloring in places (--no-color now definitively works everywhere)
-    <li> fixed issues with not being able to use IDs in place of names in some places (e.g. `db delete [id]`)
-    <li> timeout durations can now be parsed using iso8601 durations or with simple time units (ms, s, m, h)
-    <li> .astrarc parsing is stricter now
-    <li> improved .env + .ini parsing + printing
-    <li> and more.
+  <ul>
+    <li>automatically patch cqlsh script to work on machines with a newer python version as default by testing for older python versions explicitly</li>
+    <li>consistent support of the `--output` flag across all commands–either a format is supported, or the command will error out before doing anything</li>
+    <li>removed `astra-init` script in favor of the `astra compgen` command</li>
+    <li>removed `astra login` since it was just an alias of `astra setup`</li>
+    <li>`setup` command has been completely rewritten and improved to be much more interactive and user-friendly</li>
+    <li>fewer API calls will be made due to better internal caching and logic (commands may be much faster now!)</li>
+    <li>fixed inconsistent shell coloring in places (--no-color now definitively works everywhere)</li>
+    <li>fixed issues with not being able to use IDs in place of names in some places (e.g. `db delete [id]`)</li>
+    <li>timeout durations can now be parsed using iso8601 durations or with simple time units (ms, s, m, h)</li>
+    <li>.astrarc parsing is stricter now</li>
+    <li>improved .env + .ini parsing + printing</li>
+    <li>and more.</li>
+  </ul>
 </details>
 
 ## Troubleshooting
+
+### Common issues
+
+**MacOS security warnings**
+
+If you get an "unidentified developer" error on macOS, see the [macOS warning section](#-macos-warning) above.
+
+**Authentication failures**
+
+If commands fail with authentication errors:
+- Verify your token is valid and hasn't expired
+- Check that you're using the correct environment (`--env` flag)
+- Run `astra config list` to verify your configuration profile settings
+- Try running `astra setup` again to reconfigure your credentials
+
+**External programs not working (cqlsh, dsbulk, pulsar-shell)**
+
+If external programs fail to download or execute:
+- Check your internet connection
+- Verify you have write permissions to your `ASTRA_HOME` directory
+- Try removing the cached binary and letting the CLI re-download it:
+  ```bash
+  # Find the path first
+  astra db cqlsh path  # (or dsbulk path, or streaming pulsar path)
+  # Then remove the parent directory and try again
+  ```
+
+**Finding your configuration files**
+
+If you're unsure where your `.astrarc` file or home folder is located, or if you're getting warnings about multiple paths:
+- Run `astra config path` to see where your `.astrarc` file is (or would be) located
+- Run `astra config home path` to see where your Astra home folder is located
+- If you see warnings about multiple `.astrarc` files or home folders existing in different locations:
+  - Remove or migrate the lower priority files/folders (priority: custom env var > XDG spec > default home directory)
+  - Or, suppress the warning by setting `ASTRA_IGNORE_MULTIPLE_PATHS=true`
+
+**General debugging**
+
+For any issues:
+- Use the `--verbose` flag to see detailed output
+- Use the `--dump-logs` flag to save logs to a file for later inspection
+- Check the [GitHub issues](https://github.com/datastax/astra-cli/issues) for similar problems
+- Open a new issue if your problem isn't already reported

assets/demo.gif

@@ -187,7 +187,7 @@ if (-not $existingInstallPath -and (Test-Path (Join-Path $ASTRA_CLI_DIR "astra.e
 if ($existingInstallPath) {
     Write-Host ""
     Write-Host "Error: An existing astra installation was already found." -ForegroundColor Red
-    Write-Host "An existing installation was found at $(Tildify (Split-Path $existingInstallPath))`n"
+    Write-Host "An existing installation was found at $( Tildify (Split-Path $existingInstallPath) )`n"
     Write-MultiColor -Texts @("-> ", "(< astra-cli 1.x)", " Remove the existing installation manually and re-run this installer.") -Colors @("DarkCyan", "DarkGray", "Gray")
     Write-MultiColor -Texts @("-> ", "(> astra-cli 1.x)", " Run ", "astra upgrade", " to automatically update to the latest version.") -Colors @("DarkCyan", "DarkGray", "Gray", "DarkCyan", "Gray")
     Write-MultiColor -Texts @("-> ", "(> astra-cli 1.x)", " Run ", "astra nuke", " to completely remove the CLI and then re-run this installer.") -Colors @("DarkCyan", "DarkGray", "Gray", "DarkCyan", "Gray")
@@ -200,7 +200,7 @@ if ($existingInstallPath) {
 
 # Create installation directory
 New-Item -ItemType Directory -Force -Path $ASTRA_CLI_DIR | Out-Null
-Checklist "Using installation dir $($ASTRA_CLI_DIR + "\")"
+Checklist "Using installation dir $( $ASTRA_CLI_DIR + "\" )"
 
 # Download and extract
 $zipPath = Join-Path $ASTRA_CLI_DIR "astra-tmp.zip"
@@ -224,7 +224,7 @@ catch {
     }
     catch {
         Remove-Item $zipPath -ErrorAction SilentlyContinue
-        Panic "`nError: Failed to download the archive to $(Tildify $zipPath). Check your internet connection and permissions."
+        Panic "`nError: Failed to download the archive to $( Tildify $zipPath ). Check your internet connection and permissions."
     }
 }
 
@@ -244,7 +244,7 @@ try {
     Remove-Item -Recurse -Force $tempDir
 }
 catch {
-    Panic "`nError: Failed to extract the archive at $(Tildify $zipPath)."
+    Panic "`nError: Failed to extract the archive at $( Tildify $zipPath )."
 }
 finally {
     Remove-Item -Force $zipPath -ErrorAction SilentlyContinue

scripts/install.ps1

@@ -72,12 +72,12 @@ RESET=$(color sgr0)
 
 # Prelude
 echo "$PURPLE"
-echo "    _____            __                  "
-echo "   /  _  \   _______/  |_____________    "
-echo "  /  /_\  \ /  ___/\   __\_  __ \__  \   "
-echo " /    |    \\___ \  |  |  |  | \// __ \_ "
-echo " \____|__  /____  > |__|  |__|  (____  / "
-echo "         \/     \/                   \/  "
+echo "    _____            __                   "
+echo "   /  _  \   _______/  |_____________     "
+echo "  /  /_\  \ /  ___/\   __\_  __ \__  \    "
+echo " /    |    \\___  \  |  |  |  | \// __ \_ "
+echo " \____|__  /____  > |__|  |__|  (____  /  "
+echo "         \/     \/                   \/   "
 echo ""
 echo "                    Installer: $ASTRA_CLI_VERSION"
 echo "$RESET"
@@ -122,7 +122,7 @@ print_next_steps() {
     echo ""
   fi
 
-  renderComment "Append the following to your shell profile (e.g. $(underline "~/.bashrc"), $(underline "~/.zshrc"), etc.)"
+  renderComment "Append the following to your shell profile (e.g. $(underline "~/.zprofile"), $(underline "~/.bash_profile"), etc.)"
   if [ "$ASTRA_CLI_DIR_RESOLVER" = "custom" ]; then
     renderCommand "eval \"\$($(tildify "$EXE_PATH") shellenv --home \"$(tildify "$ASTRA_HOME")\")\""
   else

scripts/install.sh

@@ -90,7 +90,7 @@ try {
 } catch {
     # Try a second time
     Stop-Astra
-    Start-Sleep -Seconds 1
+    Start-Sleep -Seconds 3
     try {
         Remove-Item "${PSScriptRoot}\astra.exe" -Force
     } catch {
@@ -126,18 +126,6 @@ if (Test-Path "${AstraHome}") {
     }
 }
 
-# Determine .astrarc location
-if ($env:ASTRARC) {
-    $AstraRc = $env:ASTRARC
-} elseif ($env:XDG_CONFIG_HOME) {
-    $AstraRc = "$env:XDG_CONFIG_HOME\astra\.astrarc"
-} else {
-    $AstraRc = "$HOME\.astrarc"
-}
-
-# Remove .astrarc file (do not fail if it doesn't exist)
-Remove-Item "${AstraRc}" -Force -ErrorAction SilentlyContinue
-
 # Remove Entry from PATH
 try {
     $currentPath = Get-Env -Key 'Path'

scripts/uninstall.ps1

@@ -29,7 +29,7 @@
         " @|blue:300 *|@ Enable shell completions",
         " @|blue:300 *|@ Optionally set any other configuration environment variables.",
         "",
-        "Intended to be added to your shell profile (@|code .zshrc|@, @|code .zprofile|@, @|code .bashrc|@, etc.), but you can technically just eval it in any shell session to get completions and update your PATH for that session.",
+        "Intended to be added to your shell profile (@|code .zprofile|@, @|code .bash_profile|@, @|code .profile|@, etc.), but you can technically just eval it in any shell session to get completions and update your PATH for that session.",
     },
     descriptionHeading = "%n"
 )

src/main/java/com/dtsx/astra/cli/commands/ShellEnvCmd.java

@@ -8,6 +8,8 @@
 import com.dtsx.astra.cli.operations.config.ConfigPathOperation;
 import com.dtsx.astra.cli.operations.config.ConfigPathOperation.ConfigPathResult;
 import lombok.val;
+import org.jetbrains.annotations.Nullable;
+import picocli.CommandLine.ArgGroup;
 import picocli.CommandLine.Command;
 import picocli.CommandLine.Option;
 
@@ -21,29 +23,53 @@
     name = "path",
     description = {
         "Prints the expected path of the .astrarc file, even if does not exist.",
-        "Checks @|code ASTRARC|@ @|faint,italic (ASTRARC=~/my_folder/.my_rc)|@ -> @|code XDG_CONFIG_HOME|@ @|faint,italic ($XDG_CONFIG_HOME/astra/.astrarc)|@ -> @|code HOME|@ @|faint,italic (~/.astrarc)|@.",
+        "",
+        "The file is resolved in the following order:",
+        " @|blue:300 1.|@ The @|code ASTRARC|@ environment variable @|faint,italic (e.g. ASTRARC=~/my_folder/.my_rc)|@",
+        " @|blue:300 2.|@ The @|code XDG_CONFIG_HOME|@ spec @|faint,italic (e.g. $XDG_CONFIG_HOME/astra/.astrarc)|@",
+        " @|blue:300 3.|@ The default home directory @|faint,italic (e.g. ~/.astrarc)|@",
+        "",
+        "By default, shows informational output when running in a TTY (interactive terminal), and plain path output when piped or redirected."
     }
 )
 @Example(
     comment = "Get information about the path to the .astrarc file",
     command = "${cli.name} config path"
 )
 @Example(
-    comment = "Print only the path to the .astrarc file, without additional information",
+    comment = "Force only the plain path to the .astrarc file, without additional information",
     command = "${cli.name} config path -p"
 )
+@Example(
+    comment = "Force informational output even when piped or redirected",
+    command = "${cli.name} config path -i"
+)
 public class ConfigPathCmd extends AbstractCmd<ConfigPathResult> {
-    @Option(
-        names = { "-p", "--plain" },
-        description = "Print only the path to the .astrarc file, without additional information"
-    )
-    public boolean pathOnly;
+    @ArgGroup
+    public @Nullable OutputMode outputMode;
+
+    public static class OutputMode {
+        @Option(
+            names = { "-p", "--plain" },
+            description = "Print only the path to the .astrarc file, without additional information (always)"
+        )
+        public boolean pathOnly;
+
+        @Option(
+            names = { "-i", "--info" },
+            description = "Print informational output with context about the path (always)"
+        )
+        public boolean info;
+    }
 
     @Override
     protected OutputAll execute(Supplier<ConfigPathResult> res) {
         val data = mkData(res.get());
 
-        if (pathOnly) {
+        val pathOnly = outputMode != null && outputMode.pathOnly;
+        val info = outputMode != null && outputMode.info;
+
+        if (pathOnly || (!info && ctx.isNotTty())) {
             return OutputAll.response(res.get().path(), data);
         }