How to Use the aqua root-dir Command: A Complete Guide

The aqua root-dir command prints the absolute path to Aqua's installation root directory, which defaults to $HOME/.local/share/aquaproj-aqua on Linux/macOS or respects the AQUA_ROOT_DIR environment variable when set.

The aqua root-dir command is a utility in the aquaproj/aqua CLI that helps users and shell scripts locate where Aqua stores its installed tools and metadata. Understanding this command is essential for configuring your PATH environment variable and automating development environment setup.

What Does the aqua root-dir Command Do?

When you execute aqua root-dir, the CLI outputs a single line containing the absolute path to Aqua's root installation directory. This directory contains the bin subdirectory where Aqua places symlinks to your installed tools.

The command determines the path through the following priority:

1. Environment Variable: If AQUA_ROOT_DIR is set, that value is used exclusively.
2. XDG Base Directory: On Unix systems, it checks XDG_DATA_HOME (defaulting to $HOME/.local/share).
3. Platform Defaults: On Windows, it uses the xdg package to determine the appropriate data directory.

The final path always appends aquaproj-aqua as the subdirectory name.

How the aqua root-dir Command Works (Source Code Analysis)

Command Entry Point in pkg/cli/root/command.go

The CLI command is defined in pkg/cli/root/command.go. The New function constructs a cli.Command struct where the Action field points to the action method of the command struct.

// Simplified structure from pkg/cli/root/command.go
func New() *cli.Command {
    return &cli.Command{
        Name:   "root-dir",
        Action: cmd.action,
    }
}

Inside the action method, the command performs three main operations: it optionally starts CPU or memory profiling via profile.Start, resolves the root directory, and writes the result to standard output.

Root Directory Resolution Logic

The core logic resides in the config package. The action method calls:

rootDir := config.GetRootDir(osenv.New())

This function acts as a dispatcher that selects the appropriate implementation based on the operating system.

Unix Implementation (pkg/config/root_dir.go)

For Linux and macOS, the implementation lives in pkg/config/root_dir.go. The logic follows this exact sequence:

1. Check if AQUA_ROOT_DIR environment variable exists and is non-empty.
2. If not, check XDG_DATA_HOME.
3. If XDG_DATA_HOME is unset, default to $HOME/.local/share.
4. Append /aquaproj-aqua to the resulting path.

// Conceptual flow from pkg/config/root_dir.go
func GetRootDir(env osenv.OSEnv) string {
    if dir := env.Getenv("AQUA_ROOT_DIR"); dir != "" {
        return dir
    }
    xdgDataHome := env.Getenv("XDG_DATA_HOME")
    if xdgDataHome == "" {
        home := env.Getenv("HOME")
        xdgDataHome = filepath.Join(home, ".local", "share")
    }
    return filepath.Join(xdgDataHome, "aquaproj-aqua")
}

Windows Implementation (pkg/config/root_dir_windows.go)

For Windows environments, Aqua uses pkg/config/root_dir_windows.go. This file imports the github.com/adrg/xdg package to handle Windows-specific data directory conventions.

The Windows implementation:

1. Prioritizes AQUA_ROOT_DIR if set.
2. Uses xdg.DataHome() to retrieve the standard Windows data directory (typically %LOCALAPPDATA%).
3. Falls back to appropriate Windows defaults if needed.
4. Appends aquaproj-aqua to the final path.

Practical Examples for Using aqua root-dir

Basic Usage

Print the current Aqua root directory to verify your installation:

aqua root-dir

Output:

/home/user/.local/share/aquaproj-aqua

Configuring Your PATH

The most common use case is adding Aqua's binary directory to your shell configuration. Add this to your .bashrc, .zshrc, or .bash_profile:

export PATH="$(aqua root-dir)/bin:$PATH"

This ensures that tools installed via Aqua are available in your current shell session.

Scripting with aqua root-dir

Use the command in automation scripts to locate Aqua-managed resources:

#!/bin/bash
AQUA_ROOT=$(aqua root-dir)
AQUA_BIN="${AQUA_ROOT}/bin"

if [ -d "$AQUA_BIN" ]; then
    echo "Aqua binaries located at: $AQUA_BIN"
    ls -la "$AQUA_BIN"
else
    echo "Aqua bin directory not found"
fi

Summary

• The aqua root-dir command outputs the absolute path to Aqua's installation directory, which contains the bin subdirectory with your installed tools.
• The path resolution prioritizes the AQUA_ROOT_DIR environment variable, then falls back to XDG Base Directory standards (XDG_DATA_HOME or $HOME/.local/share on Unix, Windows-specific locations via the xdg package).
• Implementation spans pkg/cli/root/command.go for the CLI interface and pkg/config/root_dir.go (Unix) or pkg/config/root_dir_windows.go (Windows) for platform-specific logic.
• Use this command in shell scripts to dynamically configure your PATH or locate Aqua-managed binaries.

Frequently Asked Questions

What is the default aqua root directory on Linux and macOS?

By default, Aqua uses $HOME/.local/share/aquaproj-aqua on Unix-like systems. This follows the XDG Base Directory Specification, specifically checking XDG_DATA_HOME first (defaulting to $HOME/.local/share if unset) and appending aquaproj-aqua to that path.

How do I change the aqua installation directory?

Set the AQUA_ROOT_DIR environment variable to your desired path. When this variable is present, Aqua uses it exclusively instead of calculating the XDG-based default. For example: export AQUA_ROOT_DIR=/opt/aqua followed by aqua root-dir will output /opt/aqua.

Can I use aqua root-dir in shell scripts?

Yes, the command is designed for scripting. It prints only the absolute path to stdout with no additional formatting, making it ideal for command substitution. Common patterns include export PATH="$(aqua root-dir)/bin:$PATH" or assigning the output to a variable like ROOT_DIR=$(aqua root-dir).

Does aqua root-dir work the same way on Windows?

The command functions identically on Windows, outputting the appropriate path for the Windows file system. However, the underlying implementation in pkg/config/root_dir_windows.go uses the github.com/adrg/xdg package to determine the data directory (typically under %LOCALAPPDATA%) rather than Unix-style XDG variables, while still respecting the AQUA_ROOT_DIR environment variable if set.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}