Skip to content

Latest commit

 

History

History
531 lines (367 loc) · 30.5 KB

tools.md

File metadata and controls

531 lines (367 loc) · 30.5 KB

Core Features & Tools Reference Guide

This document provides a comprehensive reference for the developer tools and CLI utilities included and configured within the NREDF dotfiles ecosystem across Linux, macOS, and Windows.


Builtin Tooling Overview

All core CLI tools are declared centrally in home/dot_config/aquaproj-aqua/aqua.yaml and installed via aqua.

Category Primary Tools Role / Description
Dotfiles & Packages chezmoi, aqua, sheldon Declarative system state & tool management
Shell & History oh-my-posh, atuin, fzf, zoxide, carapace Prompt, encrypted history sync, fuzzy search, smart cd, multi-shell completion
CLI Replacements lsd, bat, delta, ripgrep, fd, procs (pst) Modern, colored replacements for ls, cat, diff, grep, find, ps auxf
Multiplexer zellij Builtin modern terminal workspace & multiplexer
File Management yazi (yy) Fast async terminal file manager with custom plugins
Git UI lazygit (lzg / lg) Interactive terminal Git management
Containers & Logs lazydocker (lzd), lazyjournal (lzj / lj), lnav Terminal UIs for Docker management, log aggregation, and SQL log analysis
System Monitoring bottom (btm) Real-time interactive system resource & process monitor
Kubernetes kubectl, kubectx, kubens, k9s, helm, stern Container orchestration, context switching, and TUI
Network & Transfers curl, wget Hardened, XDG-compliant network transfer clients
Developer Ecosystem gh, uv, ruff, mise, tealdeer (tldr) GitHub CLI, Python toolchain, runtime manager, and community-maintained man-page summaries
Repo Fleet Dashboard drydock What's uncommitted, unpushed, and unreleased across every repo under roots

Builtin Terminal Multiplexer: Zellij

Zellij is the default and builtin terminal workspace manager in NREDF. It is configured in home/dot_config/zellij/config.kdl.tmpl with the unified OneDark-Pro theme.

Zellij Modal Architecture

Zellij uses a modal interface where a shortcut switches you into a specific mode:

Normal Mode ──┬──► Ctrl + p : Pane Mode (split, focus, float, fullscreen)
              ├──► Alt  + t : Tab Mode (new tab, close tab, rename, sync)
              ├──► Ctrl + n : Resize Mode (increase/decrease dimensions)
              ├──► Ctrl + s : Scroll & Search Mode (search buffer, edit scrollback)
              ├──► Ctrl + o : Session Mode (detach, manage sessions)
              ├──► Ctrl + h : Move Mode (reorder and swap panes)
              ├──► Ctrl + b : Tmux Compatibility Mode
              └──► Ctrl + g : Locked Mode (passes all keys directly to inner apps)

Zellij Keyboard Shortcuts Cheatsheet

1. Pane Mode (Ctrl + p)

Enter pane mode, then press:

  • d: New pane split Down
  • r: New pane split Right
  • n: New generic pane
  • x: Close focused pane
  • f: Toggle fullscreen on current pane
  • w: Toggle floating panes
  • e: Toggle pane between embedded and floating
  • c: Rename pane
  • h / j / k / l (or Arrows): Move focus Left / Down / Up / Right
  • Esc or Enter: Return to Normal mode

2. Tab Mode (Alt + t)

Rebound from zellij's default Ctrl + t, which clashes with fzf's Ctrl-T file-search widget in every shell here. Ctrl + p/n/s/h/b/q (Pane/Resize/Scroll/Move/Tmux mode, Quit) also collide with Neovim and readline defaults; those are left as-is since Ctrl + g (Locked Mode) passes keys straight through to the inner app when that matters.

Enter tab mode, then press:

  • n: New tab
  • x: Close active tab
  • r: Rename tab
  • s: Toggle active sync (broadcast keystrokes to all panes in tab)
  • h / k (or ←): Go to previous tab
  • l / j (or →): Go to next tab
  • 1 – 9: Jump directly to tab 1 – 9
  • [ / ]: Break active pane out into a new tab (left/right)

3. Resize Mode (Ctrl + n)

Enter resize mode, then press:

  • h / j / k / l: Increase pane size in that direction
  • H / J / K / L: Decrease pane size in that direction
  • + / =: Increase overall size
  • -: Decrease overall size

4. Scroll & Search Mode (Ctrl + s)

Enter scroll mode, then press:

  • s: Open interactive search prompt
  • n / p: Search next / previous match
  • c: Toggle case sensitivity
  • w: Toggle whole-word matching
  • j / k: Scroll down / up line by line
  • d / u: Half-page scroll down / up
  • Ctrl + f / Ctrl + b: Full page scroll down / up
  • e: Edit Scrollback: Open the entire terminal buffer directly in Neovim!

5. Locked Mode (Ctrl + g)

Press Ctrl + g to lock Zellij. All keystrokes pass directly to inner applications (such as Neovim or remote shells) without collision. Press Ctrl + g again to unlock.

Automatic Startup & Session Attachment

  • Remote SSH Sessions: When connecting over SSH, NREDF automatically attaches or creates a host-named Zellij session (enabled by default; controlled by shell.multiplexer / NREDF_SHELL_MULTIPLEXER).
  • WSL Sessions: On Windows Subsystem for Linux (WSL), automatic multiplexer attachment is disabled by default so terminal tabs behave as independent native shells. You can opt in by:
    • Running chezmoi init --prompt && chezmoi apply and enabling the WSL multiplexer prompt (or setting wsl_multiplexer = true under [data.shell] in ~/.config/chezmoi/chezmoi.toml).
    • Exporting export NREDF_SHELL_WSL_MULTIPLEXER=true in ~/.config/bash/rc or ~/.config/zsh/rc.

Prompt: Oh-My-Posh

All five shells render the same theme, home/dot_config/oh-my-posh/config.json. Every segment below appears only when it has something to say:

  • Left, line one: OS icon, a red root indicator, user@host (only over SSH), the shell, the path, and git. The git segment shows * stashes, ~ conflicts, + staged, ! unstaged, ✘ deleted and ? untracked files. Submodule worktrees are not scanned (ignore_submodules: dirty), which keeps large repositories fast.
  • Right, line one: exit status, the duration of commands that ran longer than 3s, versions of Node, Go, Python and Rust in matching projects, the Terraform workspace, the Helm version inside a chart or helmfile directory, the Docker context when it points somewhere other than a local daemon, and the time.
  • Line two: the Kubernetes context and namespace, always visible so that you can see which cluster you are working against.
  • Tooltips (zsh, fish and PowerShell only): while you type git, lg, lzg or lazygit, the right prompt shows the upstream branch and the last commit.

Shells cache their oh-my-posh init script for 24 hours, and tooltip, transient and secondary prompt settings are part of that script. After changing those settings, run reload -c so the script is regenerated.


Encrypted Shell History: Atuin

Atuin replaces your default shell history with an SQLite database backed by end-to-end encrypted synchronization across machines.

Daily Usage

  • Search History: Press Ctrl + r in any shell (or ↑ in PowerShell).
  • Filter Modes: While searching, press:
    • Ctrl + r: Cycle search modes (HOST, SESSION, DIRECTORY, GLOBAL).
    • Tab: Return selected command to prompt without executing.
    • Enter: Execute selected command immediately.
    • Delete: Delete highlighted entry from history.

Synchronizing Machines

# First machine: create an account
atuin register -u <username> -e <email>
atuin key  # Back up your encryption key!

# Subsequent machines: log in
atuin login -u <username>
atuin sync

Interactive Fuzzy Finding: fzf & PSFzf

Configured with custom OneDark-Pro theme colors and preview commands:

Keybinding Shells Preview Action
Ctrl + t Zsh, Bash, Fish, Nushell, pwsh bat syntax highlighted preview Fuzzy search files in workspace
Alt + c / Option+c Zsh, Bash, Fish, Nushell, pwsh lsd --tree preview Fuzzy search directories and cd
Ctrl + / Any fzf window — Toggle preview window (hidden/bottom/right)
Tab / Shift+Tab Any fzf window — Multi-select items / move cursor

SSH & Network Completions

Typing ssh ** or scp ** followed by Tab automatically fuzzy searches known hosts across:

  • ~/.ssh/config and /etc/ssh/ssh_config
  • ~/.ssh/known_hosts
  • ~/.ssh/hosts and /etc/hosts

Smart Directory Jumping: zoxide

zoxide replaces the standard cd command across all shells:

  • cd <partial-name>: Jumps to the most frequently/recently visited match.
  • cd ../..: Behaves as standard relative directory traversal.
  • z <name>: Shorthand jump alias.
  • zi: Interactive fuzzy search directory picker powered by fzf.

Modern File Listing & Viewing: lsd & bat

lsd (Next-Gen ls)

  • ls: Colorized listing with file type icons.
  • ll: Long format listing with Git modified flags (--git) and permissions.
  • la: Long format including hidden dotfiles.
  • tree: Full recursive directory tree with icons.

bat (Syntax-Highlighted cat)

  • Aliased to cat in PowerShell and used as the default preview engine in fzf.
  • Uses the OneDarkPro theme (~/.config/bat/themes/OneDarkPro.tmTheme).
  • Displays line numbers, Git modifications in the gutter, and automatic syntax detection.

Fast Search & File Discovery: ripgrep & fd

ripgrep (rg)

Configured via $RIPGREP_CONFIG_PATH pointing to home/dot_config/ripgrep/config:

  • Smart Case: Case-insensitive searches when queries are lowercase; case-sensitive when uppercase characters are typed.
  • Hidden Files: Automatically searches dotfiles while ignoring internal .git repository trees.
  • Terminal Protection: Truncates lines longer than 150 columns (--max-columns=150 and --max-columns-preview) to prevent terminal freezing on minified assets.
  • OneDark-Pro Palette: Matches terminal highlights with bold blue paths (#61afef), yellow line numbers (#e5c07b), and bold red matches (#e06c75).

fd

Configured with global ignore rules in home/dot_config/fd/ignore:

  • Automatically excludes noise such as .git/, node_modules/, vendor/bundle/, __pycache__/, .venv/, .turbo/, .cache/, .DS_Store, and Thumbs.db.

Network & Transfer Utilities: curl & wget

Both utilities follow strict XDG Base Directory specifications to prevent cluttering $HOME.

curl

Configured in home/dot_config/curlrc.tmpl ($XDG_CONFIG_HOME/curlrc):

  • HTTPS Enforcement: Defaults schemeless URLs to HTTPS (proto-default = "https").
  • Automated Redirects: Automatically follows HTTP 3xx redirects (location, max-redirs = 50).
  • Compression: Enables automated gzip/brotli/zstd response decompression (compressed).
  • Resilient Timeouts: Caps connection negotiation at 30 seconds (connect-timeout = 30).
  • Error Visibility: Ensures error details remain visible even when running silent mode (show-error).

wget

Configured via $WGETRC pointing to home/dot_config/wgetrc.tmpl ($XDG_CONFIG_HOME/wgetrc):

  • Resilient Downloads: Resumes interrupted transfers (continue = on) with a 3-try limit and 30-second timeout.
  • Timestamping: Re-downloads files only when remote copies are newer (timestamping = on).
  • Security: Validates TLS certificates by default (check_certificate = on).
  • Cache Cleanliness: Relocates the HSTS tracking database to ~/.cache/wget-hsts, eliminating home directory clutter.

Terminal File Manager: Yazi

Yazi is an ultra-fast terminal file manager written in Rust.

Features & Plugins Configured

NREDF configures Yazi with the following plugins in home/dot_config/yazi/keymap.toml.tmpl:

  • Smart Enter (l): Enters directory or opens file in Neovim automatically.
  • Smart Paste (p): Intelligently pastes into the hovered folder or CWD.
  • Git VCS Changes (g c): Filters and shows only Git modified files.
  • File Permissions (c m): Quick chmod on selected files.
  • File Diff (Ctrl + d): Compare the selected file with hovered file.
  • Smart Filter (F): Interactive live filter.
  • Zoom (+ / -): Zoom in / out on hovered previews.
  • Mount (M): Interactive mount plugin.

Shell Working Directory Integration (yy)

Use the yy alias in any shell to launch Yazi. When you exit with q, your shell automatically changes directories to the folder you were navigating!


Terminal Git UI: LazyGit (lzg / lg)

Launch interactive Git management with lzg or lg (or Space g g in Neovim).

Keybinding Action
1 – 5 Jump to panel (Status, Files, Branches, Commits, Stash)
Space Stage / unstage file or hunk
c Commit staged changes (opens editor prompt)
P Push to remote repository
p Pull from remote repository
b View branch list / create branch
w Open commit message menu
e Edit selected file in Neovim
/ Search / filter items in active panel
? Show all available keybindings for the current panel
q Quit LazyGit

Configured with the OneDark-Pro color scheme and integrates with delta for side-by-side diff previews.


Git & SSH Configuration

Git reads home/dot_config/git/config.tmpl from ~/.config/git/config. It sets delta as the pager, zdiff3 conflicts, histogram diffs, rerere, fetch.prune, push.autoSetupRemote, rebase-on-pull and a set of short aliases (git st, git lg, git gone, ...).

  • Local overrides: chezmoi rewrites ~/.config/git/config on every apply, so a git config --global edit does not last. Put machine-local settings in ~/.config/git/config.local (for example git config --file ~/.config/git/config.local user.email work@example.com). It is included last, so it overrides everything, and git skips it if it does not exist.
  • Commit & tag signing: with a signing key configured (see the Secrets Guide), commits are signed. Tags are signed only on request (git tag -s), so a scripted git tag <name> still makes a lightweight tag instead of opening an editor. For gpg.format = ssh, ~/.config/git/allowed_signers is rendered from your email and public key so git log --show-signature and git verify-commit can verify your own signatures.
  • Global ignore: ~/.config/git/ignore ignores OS and editor junk (.DS_Store, Thumbs.db, *.swp, .idea/, .direnv/, ...) in every repository.
  • SSH: ~/.ssh/config loads ~/.ssh/config.d/* first, then ~/.ssh/config.override (created once, never overwritten), then the Host * defaults (agent, keep-alive, connection multiplexing). OpenSSH uses the first value it finds for each option, so the earlier files win.

Container Management: lazydocker (lzd)

lazydocker is an interactive terminal UI for both Docker and Docker Compose environments, aliased to lzd:

Keybinding Action
1 – 4 Jump panels (Services/Containers, Images, Volumes, System)
Space Pause / Unpause container
r Restart container / service
s Stop container / service
d Remove container, image, or volume
m View logs (stream container logs in dedicated viewer)
e Exec into container (opens interactive shell)
[ / ] Previous / next tab in detailed panel (Logs, Stats, Config, Top)
b Open bulk commands menu (stop all, clean all, prune)
/ Filter items in active list
? Open keybindings and help menu
q Quit lazydocker

Log Analysis & Navigation: lazyjournal (lzj / lj) & lnav

1. lazyjournal (lzj / lj)

lazyjournal is an all-in-one TUI for querying and navigating logs across multiple sources, aliased to lzj (and lj):

  • Supported Sources: Systemd journald, auditd, local log files, Docker/Podman containers, Docker Compose stacks, and Kubernetes pods.
  • Key Features: Live streaming, multi-level log syntax highlighting, regex filtering, and custom search queries.
  • Keybindings:
    • /: Start search / regex query
    • f: Open filter menu
    • h: Toggle log highlighting
    • r: Refresh / reload logs
    • ?: Open help cheat sheet
    • q: Quit

2. lnav (Log File Navigator)

lnav is an advanced log viewer with an embedded SQLite query engine:

  • Format Auto-Detection: Automatically parses syslog, Apache, nginx, JSON logs, systemd, and more without manual setup.

  • Timeline & Zoom: Press t to view logs on a timeline; press z / Z to zoom in / out.

  • Error Navigation: Jump directly to errors with e (next error) and E (previous error), or warnings with w / W.

  • Interactive Filtering:

    • & <pattern>: Filter in (show only matching lines)
    • - <pattern>: Filter out (hide matching lines)
  • SQL Queries: Query your structured log data in real time:

    ;SELECT log_time, log_level, log_message FROM log WHERE log_level = 'error' ORDER BY log_time DESC

System Resource Monitoring: bottom (btm)

bottom is an interactive, cross-platform graphical system and process monitor displaying CPU cores, memory, disk I/O, network bandwidth, and a process tree themed with OneDark-Pro:

  • ?: Open help / keybindings
  • Tab: Cycle through active widgets
  • /: Search and filter processes
  • t: Toggle process tree view
  • d / k: Send terminate/kill signal to selected process
  • s: Change process sort criteria
  • q / Ctrl + c: Quit

Markdown, System Info & Disk Usage: glow, fastfetch & dust

glow

Configured in home/dot_config/glow/glow.yml.tmpl:

  • Terminal Markdown reader configured with dark styling, mouse scrolling, and pager support.

fastfetch

Configured in home/dot_config/fastfetch/config.jsonc.tmpl:

  • Clean, structured system information dashboard themed with OneDarkPro accent colors.

dust

Configured in home/dot_config/dust/config.toml.tmpl:

  • Interactive disk usage tool configured with reverse = true (largest directories positioned at the bottom next to the prompt) and right-aligned progress bars.

Kubernetes Tooling Suite

Declarative Kubernetes management configured across all operating systems:

Command / Tool Description
k Alias for kubectl
kctx / ctx Shorthand for kubectx (interactive context selection)
kns / ns Shorthand for kubens (interactive namespace selection)
k9s Rich full-screen terminal UI for Kubernetes clusters
stern Multi-pod log tailing; home/dot_config/stern/config.yaml defaults to --tail=50 instead of the whole 48h window
kubectl getw / gety / getn kuberc aliases for get -o wide, get -o yaml and get nodes -o wide, from home/private_dot_kube/kuberc (aliases only, so scripts calling plain kubectl behave as before)

k9s Quick Keys & Plugins

Configured in home/dot_config/k9s/:

  • Resource Jump Keys:
    • F1: Pods
    • F2: Contexts
    • F3: Helm Releases
    • F4: Deployments
    • F5: StatefulSets
    • F6: Services
    • F7: Endpoints
    • F8: Ingresses
    • F9: Secrets
    • F10: Events
    • F11: PersistentVolumes
    • F12: ServiceAccounts
  • Custom Plugins:
    • a (in CSR view): Automatically approve certificate signing request (kubectl certificate approve).
    • l (in Backup view): Stream Velero backup logs.
    • Ctrl + l (in Backup view): Describe Velero backup.
  • Upstream Plugins & Skins: home/.chezmoiexternals/k9s.toml.tmpl pulls a curated set of upstream plugins and every skin from the k9s release pinned in aqua.yaml. Only plugins whose tools this repo installs are included, and ~/.config/k9s/plugins is managed exactly, so keep personal plugins in plugins.yaml.
  • Custom Jumps: jumps.yaml (cert-manager Certificate to its Secret, Karpenter NodePool to its nodes). k9s only reads jumps.yaml, not a jumps/ directory.
  • Settings: screen dumps use k9s's default per-user state directory (not a shared /tmp), and the startup check for a newer k9s release is off since aqua pins the version.

Terraform

home/dot_terraformrc.tmpl (rendered to %APPDATA%\terraform.rc on Windows) shares downloaded providers through ~/.cache/terraform/plugin-cache, which chezmoi creates, and sets disable_checkpoint = true.


Developer Ecosystem: gh, uv, ruff & mise

gh (GitHub CLI)

Configured via $GH_CONFIG_DIR pointing to home/dot_config/private_gh/config.yml.tmpl:

  • Configured to use SSH Git protocol, Neovim (editor: nvim), and delta as the default diff pager.

uv & ruff (Python Toolchain)

mise

Configured in home/dot_config/mise/config.toml.tmpl to read idiomatic version files (.nvmrc for node, .python-version for python) and auto-install missing tool runtimes. Also manages default global runtimes and tools (such as Node.js, Microsoft's apm, and Microsoft's inshellisense / is on-demand autocomplete). Tab completions across all five shells are provided by a custom Carapace spec in home/dot_config/carapace/specs/mise.yaml. Tool installations and upgrades are kept silent at prompt time (status.missing_tools = "never") and automatically synchronized via reload (whenever config.toml or config.local.toml changes) and the daily sync scheduler (reload -f).

tealdeer (tldr)

Configured in home/dot_config/tealdeer/config.toml: auto-updates its community-maintained page cache weekly in the background (auto_update_interval_hours = 168) so tldr <command> works without a manual tldr --update on a fresh machine, and prints pages straight to the terminal instead of a pager.

drydock

Configured in home/dot_config/drydock/config.toml.tmpl: scans the repos under ~/Projects (from dev.projects) for uncommitted, unpushed, or unreleased work. Its editor_command / git_client_command / terminal_command open a detached kitty window (open -na kitty --args ... on macOS, kitty --detach ... on Linux) running $EDITOR/lazygit/an interactive shell respectively; file_manager_command uses open (macOS) or xdg-open (Linux).


AI Coding CLIs: Claude Code & Antigravity

Both are installed and version-pinned by aqua (claude from anthropics/claude-code, agy from google-antigravity/antigravity-cli), so Renovate bumps them like every other tool.

Their user-level settings.json files are written by the tools themselves (/config, "always allow" grants), so chezmoi merges into them instead of replacing them. The defaults live in data files, and the merge rules in merge-json-settings.tmpl:

Tool Deployed to Defaults
Claude Code ~/.claude/settings.json claude.yaml
Antigravity CLI ~/.gemini/antigravity-cli/settings.json antigravity.yaml

Each data file has up to three sections:

  • settings: top-level keys chezmoi owns. They are reset on every apply, so change them in the data file, not in the tool.
  • merge: an object merged key by key. Your own keys under it survive.
  • union: list entries are added and never removed, so permission rules you approved while working are kept.

Everything else in the file (allow rules, hooks, model, ...) is left alone. Invalid JSON aborts the apply instead of being overwritten.

What Claude Code gets by default: background auto-update off (aqua owns the version; claude update still works), no survey or spinner tips, and deny rules for secrets. The deny rules cover .env files, ~/.ssh, the vault-fed ~/.config/nredf/mcp.json, and bw get/list/export/unlock, since BW_SESSION is present in every child process. To drop a deny rule, remove it from claude.yaml and from ~/.claude/settings.json.

zclaude: Persistent Claude Supervisor with Keep-Alive & Auto-Retry

zclaude is a cross-platform supervisor for Claude Code that integrates natively with Zellij, keeping sessions active across system idle sleep and automatically resuming long-running tasks when rate limits reset:

  • Multiplexer Integration: Uses Zellij's native CLI (dump-screen, write-chars, send-keys) instead of tmux, working identically on Linux, macOS, and Windows.
  • Dedicated AI Layout (zclaude): Features a 72% primary Claude pane flanked by a command terminal and suspended lazygit, secondary tabs for code editing and bottom monitoring, and dynamic swap layouts.
  • Status Bar: The layout's zjstatus bar shows the supervisor state and /usage quota. The supervisor pushes both with zellij pipe only when they change (plus a re-broadcast every 30s for newly opened tabs), so the bar never spawns a shell itself. The same values are also written to ~/.local/state/zclaude/status and usage.
  • System Keep-Alive: Prevents system and idle sleep while Claude is active and while waiting out limits (caffeinate on macOS, Win32 SetThreadExecutionState on Windows, and systemd-inhibit on Linux).
  • Auto-Resumption: Accurately parses limit reset times (e.g. resets 3:15 PM or relative duration) from viewport dumps and transcripts, safely dismisses any interactive /rate-limit-options dialog with Esc, and injects continue once the reset time (+ safety margin) arrives. Handles transient 529/503 overloads with progressive backoff.
  • Claude CLI Option Parity: Forwards common Claude Code flags:
    • -r, --resume [ID]: Resume an existing session or open the interactive picker.
    • -c, --continue: Continue the latest session in the directory.
    • -p, --print: Run non-interactively and stream response.
    • -m, --model <MODEL>: Switch model (sonnet, opus, haiku).
    • --dangerously-skip-permissions: Bypass permission prompts for unattended execution.
    • --effort <low|medium|high|max>: Control reasoning effort depth.
    • -w, --worktree [NAME]: Branch off into an isolated git worktree.
  • Dual Execution Modes:
    • Integrated run: zclaude [args...] wraps Claude directly in the current Zellij pane (or starts a Zellij session if run outside).
    • Watcher mode: zclaude -W/--watch [pane_id] monitors an existing Claude pane in Zellij as a sidecar or companion pane.

Package & Tool Management: aqua

NREDF uses aqua to declaratively install, lock, and manage CLI tools across Linux, macOS, and Windows.

Common Commands

aqua install             # Install all packages declared in aqua.yaml
aqua install -a -l       # Install and link all packages to bin/
aqua update              # Update package versions
aqua which <cmd>         # Show which binary aqua executes for <cmd>
aqua vacuum -d 30        # Clean up package versions unused for 30+ days

Avoiding GitHub API Rate Limits

Aqua queries the GitHub API to download binaries. To eliminate rate limit errors:

  • Automatic Secret Store Sync (Recommended): Use the builtin Secrets Management Guide to automatically resolve and populate AQUA_GITHUB_TOKEN from Bitwarden, KeePassXC, or 1Password.
  • System Keyring / Local File Fallback: Run nredf_aqua_token_setup to store a token in your OS keyring (or in ~/.config/nredf/aqua.env on headless/WSL systems where no secret service is available).
  • Manual Environment Variable: Export AQUA_GITHUB_TOKEN in your environment. aqua also falls back to GITHUB_TOKEN, but avoid that for an aqua-only token: gh prefers GITHUB_TOKEN over its own login.