🐙 Argonaut — Argo CD TUI

Argonaut is a keyboard-first terminal UI for Argo CD, built with Bubbletea. Browse apps, scope by clusters/namespaces/projects, stream live resource status, trigger syncs, inspect diffs in your favorite pager, and roll back safely — all without leaving your terminal.

❤️ 🐶  Inspired by the great UX of k9s — but for Argo CD.

---

📦 Prerequisites

• Argo CD CLI installed
• Delta installed for enhanced diffs (optional, falls back to git)

---

🚀 Installation methods

<details> <summary><strong>Install Script (Linux/macOS)</strong></summary>

curl -sSL https://raw.githubusercontent.com/darksworm/argonaut/main/install.sh | sh

The install script automatically detects your system (including musl vs glibc on Linux) and downloads the appropriate binary from the latest release.

You can also install a specific version:

curl -sSL https://raw.githubusercontent.com/darksworm/argonaut/main/install.sh | sh -s -- v1.13.0

</details> <details> <summary><strong>Homebrew (Linux/MacOS)</strong></summary>

brew tap darksworm/homebrew-tap
brew install darksworm/tap/argonaut

</details> <details> <summary><strong>AUR (Arch User Repository)</strong></summary>

⚠️ AUR uploads are currently disabled on aur.archlinux.org, so these packages may lag behind the latest release. In the meantime, run :upgrade inside argonaut to update to the latest version.

yay -S argonaut-bin

Or, to track the latest commit on main (rebuilt from source on install):

yay -S argonaut-git

</details> <details> <summary><strong>Nix</strong></summary> With Nix and Flakes enabled, you can run or install Argonaut from nixpkgs or directly from the repository.

nixpkgs

Argonaut is currently available on the unstable channel of nixpkgs. So you can install it using

nix-env -iA nixos.argonaut

On other systems (macOS, non-NixOS Linux):

nix-env -iA nixpkgs.argonaut

or by adding it to your systemPackages.

environment.systemPackages = with pkgs; [ argonaut ];

Run Directly

To run Argonaut without permanently installing it, use the nix run command:

nix run github:darksworm/argonaut

Development Shell

To enter a development shell with Argonaut and its dependencies (like Go, Delta, and Argocd) available for development, use the nix develop command:

nix develop github:darksworm/argonaut

Flakes

If you are using Flakes to manage your systems add this to your Flake:

inputs = {
  argonaut = {
    url = "github:darksworm/argonaut";
    inputs.nixpkgs.follows = "nixpkgs";
  };
  # ...
}

</details> <details> <summary><strong>Docker</strong></summary>

Pull the image:

docker pull ghcr.io/darksworm/argonaut:latest

Run with mounted Argo CD config (as your host user to preserve permissions):

docker run -it --rm \
  -u $(id -u):$(id -g) \
  -v ~/.config/argocd:/home/appuser/.config/argocd:ro \
  ghcr.io/darksworm/argonaut:latest

The container needs access to your Argo CD configuration for authentication. The :ro flag mounts it as read-only for security.

</details> <details> <summary><strong>Download a binary</strong></summary>

You can download binaries and packages in from the latest release.

</details>

⚡ Quickstart

# Log in to your Argo CD server
argocd login

# Start Argonaut
argonaut

---

✨ Highlights

• Instant app browsing with live updates (NDJSON streams)
• Scoped navigation: clusters → namespaces → projects → apps
• Command palette (:) for actions: sync, diff, rollback, resources, etc.
• Live resources view per app with health & sync status
• Events & sync status pane beside the resource tree — Kubernetes events and the last sync operation for whatever row you're on, auto-refreshing
• External diff integration: prefers delta, falls back to git --no-index diff | less
• Guided rollback with revision metadata and progress streaming
• Execute actions on resources — dynamically discovered per resource, including Argo Rollouts and any custom-defined actions
• Keyboard-only workflow with Vim-like navigation

---

📸 Screenshots

Live Apps

<img src="assets/argonaut_apps.png" alt="Apps list"/>

Sync

<img src="assets/argonaut_sync.png" alt="Sync apps"/>

Live resource tree and events

<img src="assets/argonaut_events.gif" alt="Events and sync status pane following the tree selection"/>

Diff

<img src="assets/argonaut_diff.png" alt="External diff"/>

Rollback

<img src="assets/argonaut_rollback.png" alt="Rollback flow"/>

Delete apps

<img src="assets/argonaut_delete_apps.png" alt="Delete apps"/>

Execute actions

<img src="assets/argonaut_resource_actions.png" alt="Execute actions modal — dynamically lists actions for the selected resource"/>

Enjoy colorful themes

<img src="assets/argonaut_themes.gif" alt="Many themes to choose from"/>

And much more

<img src="assets/argonaut_help.png" alt="the :help command describes all commands"/>

Advanced Features

Client certificate authentication

Argonaut supports client certificate authentication. You just need to pass a couple arguments to the argonaut command:

argonaut --client-cert=/path/to/cert --client-cert-key=/path/to/key

Self-signed certificates

If your Argo CD server uses a self-signed certificate, you can provide a custom CA certificate to trust:

argonaut --ca-cert=/path/to/ca.crt

Port-forward mode

If your Argo CD server isn't directly accessible (e.g., running in a private cluster), Argonaut can connect via kubectl port-forward:

# Configure ArgoCD CLI for port-forward mode
argocd login --port-forward --port-forward-namespace argocd

# Start Argonaut (automatically detects port-forward mode)
argonaut

Requirements:

• kubectl configured with access to the cluster
• ArgoCD server pod running in the target namespace

Custom namespace: If ArgoCD is installed in a different namespace, add to your config:

# ~/.config/argonaut/config.toml
[port_forward]
namespace = "my-argocd-namespace"

---

⚙️ Configuration

Argonaut stores its configuration in a TOML file at ~/.config/argonaut/config.toml (or $XDG_CONFIG_HOME/argonaut/config.toml).

You can override the config path with the ARGONAUT_CONFIG environment variable.

Example Configuration

[appearance]
theme = "tokyo-night"

[appearance.overrides]
# Override individual theme colors (hex format)
# accent = "#ff79c6"
# success = "#50fa7b"

[sort]
field = "name"      # name, sync, health
direction = "asc"   # asc, desc

[k9s]
command = "k9s"           # Path to k9s executable
context = ""              # Override Kubernetes context for k9s

[diff]
viewer = ""               # Interactive diff viewer (e.g., "code --diff {left} {right}", "meld {left} {right}")
formatter = ""            # Diff formatter command (e.g., "delta --side-by-side")

[events]
refresh_interval = "10s"  # How often the events/status pane refetches ("0" disables)
auto_open = true          # Open the pane automatically in the resource tree view

[http_timeouts]
request_timeout = "10s"   # Timeout for HTTP requests (increase for large deployments)

[updates]
check_enabled = true      # Set to false to disable the GitHub release-check on startup

# Start in clusters view instead of apps (supports :command syntax)
default_view = "clusters"

Configuration Options

[appearance]

| Option | Description | Default | |--------|-------------|---------| | theme | Color theme name (see available themes below) | tokyo-night |

Available themes:

• Dark themes: catppuccin-mocha, dracula, gruvbox-dark, monokai, nord, one-dark, oxocarbon, solarized-dark, tokyo-night, tokyo-storm
• Light themes: catppuccin-latte, gruvbox-light, one-light, onehalf-light, solarized-light
• Accessibility: colorblind-safe, grayscale-lowchroma, high-contrast
• Special: inherit-terminal (uses your terminal's ANSI color palette)

You can also change the theme at runtime using the :theme <name> command.

[appearance.overrides]

Override individual theme colors with hex values. Available color keys:

• accent, warning, dim, success, danger, progress, unknown, info, text, gray
• selected_bg, cursor_selected_bg, cursor_bg, border, muted_bg, shade_bg, dark_bg

[sort]

| Option | Description | Default | |--------|-------------|---------| | field | Sort field (name, sync, health) | name | | direction | Sort direction (asc, desc) | asc |

You can also change sorting at runtime using the :sort <field> <direction> command.

[k9s]

Integration settings for k9s, the Kubernetes TUI.

| Option | Description | Default