Airnity CLI

This project aims to simplify the Airnity developer life.

It is a Command Line Interface to automate several boring and repetitive tasks.

Install

Auto-detects your OS and architecture, downloads the latest release, and installs it (to ~/.local/bin on macOS/Linux, or %LOCALAPPDATA%\airnity\bin on Windows):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/airnity/airnity-cli-releases/main/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/airnity/airnity-cli-releases/main/install.ps1 | iex

On macOS/Linux make sure ~/.local/bin is in your $PATH (the Windows script adds its dir to your PATH automatically). Once installed, upgrade later with airnity upgrade.

You are good to go!

External Requirements

This binary requires the following tools and components to be installed:

1. Google Cloud SDK (gcloud)

   The gcloud command-line tool is essential for interacting with Google Cloud services.

   • Installation Guide

2. gke-gcloud-auth-plugin Component

   Required for authenticating with Google Kubernetes Engine (GKE).

   gcloud components install gke-gcloud-auth-plugin

3. GitHub CLI (gh) (optional)

   Used by the interactive TUI to authenticate GitHub API calls (via gh auth token). Alternatively, set $GITHUB_TOKEN.

   • Installation Guide

4. GPG (gpg) (optional)

   Required for the airnity gpg generate command.

   • Usually pre-installed on macOS and Linux. On macOS you can install it via brew install gnupg.

5. psql client (optional — only for airnity db connect)

   The PostgreSQL command-line client, needed for the psql action (--psql / the databases menu item). Not required for --gui or --proxy.

   • macOS: brew install libpq (then add it to your PATH, e.g. brew link --force libpq), or brew install postgresql@16.
   • Debian/Ubuntu: sudo apt install postgresql-client
   • Fedora/RHEL: sudo dnf install postgresql

6. pgAdmin (optional — only for airnity db connect --gui)

   Required for the pgAdmin action. See the db connect requirements below for the full setup (desktop app and server package, plus a one-time first launch).

   • Download pgAdmin

Config Management

The airnity CLI uses the config file ${HOME}/.airnity.yaml, which is created with default values if it doesn't exist.

Displaying the Current Configuration

You can display the current configuration using the config get command:

airnity config get

You can customize the newly created ${HOME}/.airnity.yaml as needed.

Commands

The Airnity CLI provides various commands organized by functionality:

Version Information

airnity version

Display version information including git commit and build details.

Authentication

The CLI manages two independent auth systems: Keycloak (internal SSO) and GCloud.

Unified Login/Logout

# Authenticate with both Keycloak and GCloud
airnity login

# Authenticate with Keycloak only
airnity login -k

# Authenticate with GCloud only
airnity login -g

# Logout from both Keycloak and GCloud
airnity logout

# Logout from Keycloak only
airnity logout -k

# Logout from GCloud only
airnity logout -g

Keycloak Auth

# Authenticate with Keycloak (OAuth2 + PKCE)
airnity auth login

# Force re-authentication
airnity auth login -f

# Logout from Keycloak
airnity auth logout

# Show current authenticated user
airnity auth whoami

# Check authentication status
airnity auth status

# Print access token to stdout (useful for manual API calls)
airnity auth print-access-token

# Show raw token details (debug)
airnity auth debug-tokens

GCloud Auth

# Check and authenticate GCloud credentials
airnity gcloud login

# Revoke GCloud tokens
airnity gcloud logout

Local HTTP Server

# Start a local HTTP server on 127.0.0.1:47823 (Ctrl+C to stop)
airnity serve

# Override the default port
airnity serve --port 9001

# From another terminal, once running:
curl http://127.0.0.1:47823/auth/token

Configuration Management

# Display current configuration
airnity config get

# Set individual configuration values
airnity config set k8s.kubeconfigPath "~/.kube/custom-config"
airnity config set ai.bifrostUrl "https://bifrost.airnity.io/anthropic"

# Register this machine's Tailscale IP with the IDP backend
airnity config register-tailscale-ip            # auto-detects via `tailscale ip -4`
airnity config register-tailscale-ip 100.1.2.3  # or pass the IP explicitly

The config set command allows you to update individual configuration values using dot notation for nested keys. Valid keys are:

• editor: Editor used by the CLI
• k8s.kubeconfigPath: Path to your Kubernetes config file
• ai.bifrostUrl: Bifrost API base URL

The config register-tailscale-ip command registers this machine's Tailscale IP with the IDP backend. With no argument the IP is auto-detected by running tailscale ip -4; pass an explicit IP to override detection.

Kubernetes Management

# List all available Kubernetes clusters
airnity k8s list clusters

# Generate kubeconfig files for all clusters
airnity k8s get kubeconfigs

# Use private endpoints for GKE clusters
airnity k8s get kubeconfigs --private-endpoints

Docker Registry

# Login to GCP Docker registries
airnity docker login

Database Management

Connect to Cloud SQL and AlloyDB instances over a local, IAM-authenticated proxy — no passwords, no IP allow-listing. airnity db connect discovers the engines you can reach, lets you pick one, then either drops you into a psql session, opens pgAdmin, or just holds a proxy open for your own tools.

# Interactive: pick an engine, then choose an action from the menu
airnity db connect

# Same command, short aliases also work
airnity db c
airnity db conn

Interactive flow

1. Engine picker — lists every Cloud SQL / AlloyDB engine. Engines you lack a database account on are greyed out at the bottom under a "No access" divider and can't be selected.

2. Action menu — after choosing an engine, pick what to do (default highlight on databases). Press the bracketed shortcut key, or move with ↑/↓ and press enter:

   Connect to <engine>
   
   > [d] databases      browse and psql into one
     [g] pgAdmin GUI    open pgadmin (whole engine)
     [p] proxy only     keep a local proxy open (whole engine)
   

   • [d] databases — lists the databases in the engine, you pick one, and it opens a psql session connected to it. (If the engine has a single database it's selected automatically; if it reports none, it falls back to postgres.)
   • [g] pgAdmin GUI — imports the engine as a server into pgAdmin and launches it. pgAdmin browses all databases itself, so there's no database picker. The CLI holds the proxy open until you quit pgAdmin (or press q).
   • [p] proxy only — starts the proxy and prints a ready-to-paste connection string, then stays running until you press q. Point any client (psql, DBeaver, an app) at 127.0.0.1:<port>.

3. Press q / ctrl+c at any screen to tear down the proxy and quit.

Flags

Action flags skip the menu and run that action directly. They are mutually exclusive.

Flag	Description
--psql	Open an interactive psql session (goes straight to the database picker).
--gui	Open the selected engine in pgAdmin.
--proxy	Start a local proxy and keep it open (no psql / pgAdmin).
--engine <name>	Connect directly to this engine by name, skipping the engine picker. Errors if the name is unknown, matches more than one engine, or you lack access to it. Supports shell completion (served from the local cache — no network).
--db <name>	Connect directly to this database, skipping the database picker. Applies to the psql path only; ignored (with a warning) for --proxy / --gui.
--refresh	Bypass the cached instance list and re-scan GCP.

With no action flag the interactive menu is shown. --engine only skips the engine picker — the action menu still appears unless an action flag is also given.

# Skip the menu: psql straight into a chosen database
airnity db connect --engine my-engine --db my-app --psql

# Open pgAdmin for a specific engine, no prompts
airnity db connect --engine my-engine --gui

# Just give me a proxy on this engine
airnity db connect --engine my-engine --proxy

# Force a fresh scan of available engines
airnity db connect --refresh

Requirements

• Authenticated with gcloud (airnity gcloud login) — the proxy authenticates as your active gcloud account via IAM, so the matching database role must already exist on the engine. If your gcloud login or application-default credentials are missing or expired, db connect re-authenticates in place before connecting.
• An interactive terminal (the command refuses to run otherwise). --plain / --no-color render the TUI without color but don't disable it.

Each action has its own external dependency. They are independent — you only need the tool for the action you actually use (--proxy needs neither):

• psql action (--psql / databases) — psql must be on your PATH. If it isn't, the psql action fails with psql not found — install PostgreSQL client tools; the GUI and proxy actions are unaffected.

  • macOS: brew install libpq (then brew link --force libpq), or brew install postgresql@16.
  • Debian/Ubuntu: sudo apt install postgresql-client
  • Fedora/RHEL: sudo dnf install postgresql

• pgAdmin action (--gui) — needs a working pgAdmin desktop install, and specifically:

  1. The pgadmin4 launcher on your PATH — otherwise pgadmin4 not found on PATH.
  2. The pgAdmin server files (web/setup.py and the bundled venv), i.e. the pgadmin4-server package — otherwise pgAdmin server files not found … is pgadmin4-server installed?.
  3. pgAdmin launched once beforehand, so its config database (~/.pgadmin/pgadmin4.db) exists — otherwise pgAdmin desktop database not found … launch pgAdmin once first.

  Install from the pgAdmin download page. On Debian/Ubuntu the pgadmin4-desktop package pulls in pgadmin4-server; after installing, run pgAdmin once and close it before using --gui. Also quit pgAdmin before connecting — the import step needs exclusive access to its config database.

AI-Powered Developer Tools

# Generate an AI-powered commit message from staged changes
airnity ai commit

# Use a specific model
airnity ai commit --model claude-sonnet

# Show detailed context sent to AI
airnity ai commit -v

The ai commit command analyzes staged git changes and generates conventional commit messages using Claude via Bifrost.

Claude Code Configuration

# Install the bifrost MCP server and configure Claude Code's global settings.json
# (honors CLAUDE_CONFIG_DIR if set, defaulting to ~/.claude/settings.json)
airnity claude configure

# Toggle MCP servers on/off for the current project
airnity claude mcp manage

The claude command manages Claude Code configuration: bifrost MCP setup and per-project MCP server permissions (written to .claude/settings.local.json).

Argo Render & Diff

Run these from inside an argo-* repository.

# Stream every (app, cluster) variant as a multi-document YAML
airnity argo render

# Filter by app and/or cluster (both flags are repeatable)
airnity argo render --app my-app --cluster my-cluster

# Diff origin/main against your merged working tree
airnity argo diff

# Open the diff in difit (browser)
airnity argo diff --browser

The argo command mirrors the TUI's Argo Render / Argo Diff tabs from the command line.

Certificates

# Show whether the Airnity Root CA is trusted system-wide
airnity certs ca status

# Install the Airnity Root CA into the OS trust store (requires sudo/admin)
airnity certs ca install

# Print your personal TLS material (ca.crt, tls.crt, tls.key) labeled
airnity certs user

# Print a single key's PEM contents (pipe-friendly)
airnity certs user tls.crt | openssl x509 -noout -subject

The certs ca commands manage trust of the embedded Airnity Root CA, required to access *.airnity.private URLs.

The certs user command prints your personal TLS certificate and key issued by the IDP backend. With no argument all keys are printed labeled; pass a single key name (ca.crt, tls.crt, or tls.key) to print only its PEM contents to stdout.

Wazuh Security Management

# Configure and enroll Wazuh agent
airnity wazuh configure

# Display real-time Wazuh agent logs
airnity wazuh print-logs

# Display current Wazuh agent configuration
airnity wazuh print-config

# Display Wazuh agent version
airnity wazuh version

CLI Updates

# Upgrade to the latest version
airnity upgrade

# Use custom proxy for updates
airnity upgrade --proxy-url https://my-proxy.example.com

Git Hooks Management

# Check git hooks installation status
airnity githooks status

# Install global git hooks (automatically configures Git)
airnity githooks install

# Create a backup of current git hooks
airnity githooks backup

# Remove global git hooks
airnity githooks uninstall

The githooks command manages global git hooks that automate common development tasks for Airnity repositories. These hooks help maintain consistent development workflows and standards.

Important Note: When git hooks are configured globally via core.hooksPath, they completely override repository-level hooks in .git/hooks. This is why the airnity githooks command installs all standard git hook files - even if a specific hook doesn't perform any action, it must exist to allow repository-level hooks to be called through the run-repo-hook mechanism.

Features

• Automatic Ticket Number Insertion: Extracts ticket numbers from branch names and appends them to commit messages
  • Branch pattern tid-123-feature-description -> Commit message gets (tid#123) appended
  • Branch pattern bid-456-bug-fix -> Commit message gets (bid#456) appended
• Organization Filtering: Only executes for repositories in the airnity GitHub organization
• Smart Detection: Won't duplicate ticket numbers if already present in the commit message
• Repository Hook Integration: Allows individual repositories to override or extend global hooks

Subcommands

• status: Shows whether git hooks are installed, their location, installation date, and any missing hook files
• install: Creates ~/.githooks directory, installs all necessary hook files with proper permissions, and automatically configures Git to use them globally (git config --global core.hooksPath ~/.githooks)
• backup: Creates a timestamped backup of your current git hooks configuration (useful before making changes)
• uninstall: Removes the global git hooks installation completely

The git hooks are installed globally in your HOME directory (~/.githooks) and work with all Git repositories in your user account. The installation process automatically configures Git to use these hooks globally.

GPG Keys Generation

airnity gpg generate

The gpg generate command automates the creation of a GPG keypair along with subkeys for signing, encryption, and authentication. This process isolates the keys within a temporary GNUPGHOME directory, ensuring your default keyring remains untouched. The command will:

• Generate a new master key for certification.
• Generate subkeys for signing, encryption, and authentication.
• Export the master key, subkeys, and public key to .key files
• Generate a revocation certificate
• Copy the generated passphrase to your clipboard for secure storage.

Once the key generation process is complete, the following files will be available in the temporary directory displayed by the script (e.g., /tmp/gnupg_202410141642_Fo2GaO):

• master.key: This is your master secret key. Do not share this key with anyone.
• sub.key: This contains your secret subkeys for signing, encryption, and authentication.
• pub.key: This is your public key. You can share this with anyone who needs to encrypt messages to you or verify your signatures.
• revoke.asc: This is a revocation certificate that can be used to invalidate your keys if they are ever compromised or lost.

Next Steps: Storing Keys/Passphrase & import into your keyring

To save, import the keys into your keyring and verify that it is working, you can follow the documentation here : https://airnity.fibery.io/Knowledge_Management/How_to/Generate-and-manage-your-GPG-keys-153/anchor=Backup--c7b633bb-103c-4934-94ca-e4456b267071

For the cleanup part you just have to delete the folder mentioned above (e.g., /tmp/gnupg_202410141642_Fo2GaO)

Shell Completion

airnity supports tab-completion for commands, flags, and dynamic values such as db connect --engine <TAB> (the engine list is served from the local cache — no network).

Completion is opt-in: you load a small script once that tells your shell to ask airnity for suggestions. The script does not contain the suggestions themselves — they are fetched live from the binary on each <TAB>, so they stay current.

Pick your shell:

# zsh (oh-my-zsh) — autoloaded on next shell start
airnity completion zsh > ~/.oh-my-zsh/cache/completions/_airnity
# zsh (plain) — ensure `autoload -Uz compinit; compinit` is in ~/.zshrc, then:
airnity completion zsh > "${fpath[1]}/_airnity"

# bash — requires the bash-completion package
airnity completion bash | sudo tee /etc/bash_completion.d/airnity > /dev/null

# fish
airnity completion fish > ~/.config/fish/completions/airnity.fish

# powershell — add to your $PROFILE
airnity completion powershell | Out-String | Invoke-Expression

Restart your shell (exec zsh / open a new terminal) afterwards. If completion still falls back to filenames in zsh, clear the completion cache once: rm -f ~/.zcompdump* && exec zsh.

Run airnity completion <shell> --help for the details of any shell. Re-run the command above after upgrading airnity if new commands or flags were added.