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

> Learn how to use the aqua root-dir command to find Aqua's installation directory on Linux, macOS, or Windows. Discover the default path and environment variable settings.

- Repository: [aquaproj/aqua](https://github.com/aquaproj/aqua)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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](https://github.com/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`](https://github.com/aquaproj/aqua/blob/main/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.

```go
// 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:

```go
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`](https://github.com/aquaproj/aqua/blob/main/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.

```go
// 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`](https://github.com/aquaproj/aqua/blob/main/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:

```bash
aqua root-dir

```

Output:

```text
/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`:

```bash
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:

```bash
#!/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`](https://github.com/aquaproj/aqua/blob/main/pkg/cli/root/command.go)** for the CLI interface and **[`pkg/config/root_dir.go`](https://github.com/aquaproj/aqua/blob/main/pkg/config/root_dir.go)** (Unix) or **[`pkg/config/root_dir_windows.go`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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.