https://github.com/tesserix/cloudnav
Fast, keyboard-driven multi-cloud TUI for Azure, GCP, and AWS. Drill through tenants, subscriptions, projects, accounts, resources, costs, and IAM from one terminal.
https://github.com/tesserix/cloudnav
aws azure bubbletea cli cost-management gcp go multi-cloud pim tui
Last synced: 28 days ago
JSON representation
Fast, keyboard-driven multi-cloud TUI for Azure, GCP, and AWS. Drill through tenants, subscriptions, projects, accounts, resources, costs, and IAM from one terminal.
- Host: GitHub
- URL: https://github.com/tesserix/cloudnav
- Owner: tesserix
- License: apache-2.0
- Created: 2026-04-17T08:03:36.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-04-17T13:33:04.000Z (about 1 month ago)
- Last Synced: 2026-04-17T13:36:48.456Z (about 1 month ago)
- Topics: aws, azure, bubbletea, cli, cost-management, gcp, go, multi-cloud, pim, tui
- Language: Go
- Homepage: https://github.com/tesserix/cloudnav
- Size: 159 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Notice: NOTICE
Awesome Lists containing this project
README
# cloudnav
A fast, keyboard-driven multi-cloud navigator. One TUI for **Azure**, **GCP**, and **AWS** — drill through tenants, subscriptions, projects, accounts, resource groups, resources, costs, and IAM without leaving the terminal.
[](https://github.com/tesserix/cloudnav/releases)
[](https://github.com/tesserix/cloudnav/actions/workflows/ci.yml)
[](https://pkg.go.dev/github.com/tesserix/cloudnav)
[](https://goreportcard.com/report/github.com/tesserix/cloudnav)
[](LICENSE)
```
┌─ cloudnav ────────────────────────────── azure • Platform-Prod ─┐
│ azure › Platform-Prod › resource groups 47 items │
├─────────────────────────────────────────────────────────────────┤
│ NAME LOCATION STATE COST │
│ Yellowfin-container-testing uksouth OK £2,355 │
│ nonprod-uksouth-baseline-rg uksouth OK £869 │
│ ... │
├─────────────────────────────────────────────────────────────────┤
│ ↵ open / search c costs o portal p PIM r refresh ? help │
└─────────────────────────────────────────────────────────────────┘
```
## Read-only by default
cloudnav is a **navigator**, not an orchestrator. Every command is read-only
unless it's explicitly documented as mutating and requires `--yes`:
- `vm start` / `vm stop` — start/stop VMs (opt-in mutation, `--yes` required).
- `pim activate` — requests time-bound role elevation via the cloud's own PIM/SSO/JIT surface. This *changes IAM state* but doesn't create resources.
Nothing else writes — not `ls`, `cost`, `advisor`, `doctor`, the TUI, or
anything in the palette.
## Why
Jumping between `az`, `gcloud`, `aws`, the three web portals, and half a dozen cost dashboards wastes minutes every time. `cloudnav` puts it all behind one keyboard-first TUI:
- **Unified hierarchy** — Azure tenants/subs/RGs, GCP orgs/projects, AWS orgs/accounts/regions all rendered the same way.
- **Real auth** — no new credentials. Uses whatever `az`/`gcloud`/`aws` already have logged in (SSO, federated, SP, workload identity).
- **PIM-first on Azure** — list and activate eligible roles from inside the TUI.
- **Costs inline** — 30-day spend as a sortable column per resource group / project / account.
- **Portal handoff** — one keystroke opens the current row in the cloud's web console.
- **CLI escape hatch** — `x` runs any provider CLI command inside the current context (subscription / project / account already selected).
## Install
### Homebrew
```bash
brew tap tesserix/tap
brew install cloudnav
```
### Go
```bash
go install github.com/tesserix/cloudnav/cmd/cloudnav@latest
```
### Binary
Grab the latest from [Releases](https://github.com/tesserix/cloudnav/releases) — `darwin`/`linux`/`windows` on `amd64` and `arm64`.
## Prerequisites
`cloudnav` wraps the cloud providers' own CLIs. Install whichever you need:
| Provider | CLI | Auth |
|---------|-----|------|
| Azure | [`az`](https://learn.microsoft.com/cli/azure/install-azure-cli) | `az login` |
| GCP | [`gcloud`](https://cloud.google.com/sdk/docs/install) | `gcloud auth login` + `gcloud auth application-default login` |
| AWS | [`aws`](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) | `aws configure sso` or `aws configure` |
Run `cloudnav doctor` to verify everything is wired up.
## Quickstart — step by step
1. **Install the tool** (pick one of the options above).
2. **Log in to the cloud you care about** using its own CLI:
```bash
az login # Azure
gcloud auth login # GCP
aws configure sso # AWS (recommended)
```
3. **Verify everything is wired up:**
```bash
cloudnav doctor
```
Expected output:
```
✓ azure you@example.com
✓ gcp you@example.com
✓ aws arn:aws:iam::123456789012:user/you
```
4. **Launch the TUI:**
```bash
cloudnav
```
Use `↑`/`↓` (or `j`/`k`) to move, `↵` to drill down, `esc` to go back, `?` for help, `q` to quit.
5. **Open the current selection in the cloud portal** with `o`.
6. **Run a CLI command in the current scope** with `x` — cloudnav will pre-fill the right `--subscription` / `--project` / `--profile`.
7. **(Azure only) List and activate PIM roles** with `p`.
### Non-interactive / scripting
```bash
cloudnav ls azure subs --json | jq '.[].name'
cloudnav ls azure rgs --subscription
cloudnav ls azure resources --subscription --resource-group my-rg --json
```
## Keybindings
| Key | Action |
|-----|--------|
| `↵` / `l` | Drill down |
| `esc` / `h` | Back up one level |
| `j` `k` / `↑` `↓` | Move selection |
| `/` | Fuzzy search current view |
| `:` | Command palette — switch cloud, tenant, subscription |
| `c` | Toggle cost column |
| `s` | Cycle sort (name → cost → state) |
| `o` | Open selected resource in cloud portal |
| `i` | Show full JSON detail |
| `p` | PIM — list/activate eligible roles (Azure) |
| `x` | Exec provider CLI in current context |
| `r` | Refresh |
| `f` | Bookmark current view |
| `?` | Help |
| `q` / `ctrl+c` | Quit |
## Configuration
`cloudnav` reads `~/.config/cloudnav/config.yml` (macOS/Linux) or `%APPDATA%\cloudnav\config.yml` (Windows). Everything is optional; sensible defaults apply.
```yaml
default_provider: azure
show_cost: true
theme: dark # dark | light | auto
bookmarks:
- provider: azure
path: subs//rgs
cache_ttl: 10m
```
Override per-invocation with env vars — `CLOUDNAV_THEME`, `CLOUDNAV_NO_COLOR`, `CLOUDNAV_LOG_LEVEL`.
### cloudnav never stores your credentials
- cloudnav does **not** read, write, or cache tokens, keys, passwords, or refresh tokens.
- All authentication is delegated to the wrapped CLIs (`az`, `gcloud`, `aws`). When you run `cloudnav`, it inherits their logged-in session for the duration of the subprocess call.
- The optional config file holds preferences only (theme, bookmarks, sort order). You can delete it at any time with no loss of access.
- Logs go to `~/.local/state/cloudnav/cloudnav.log` (Linux) / `~/Library/Logs/cloudnav/cloudnav.log` (macOS) and contain only the CLI commands we executed plus any stderr — never tokens.
## Non-interactive / headless use
cloudnav is a TUI by default, but every navigation step is also exposed as a scriptable command:
```bash
cloudnav ls azure subs --json | jq '.[].name'
cloudnav ls azure rgs --subscription --json
cloudnav ls azure resources --subscription --resource-group my-rg --json
```
When stdout is not a terminal (pipe, CI, Docker without `-t`), `cloudnav ls` will emit plain output by default and `--json` switches to machine-readable. The TUI binary itself requires a terminal; on headless machines use `cloudnav ls`, `cloudnav doctor`, and `cloudnav version` only.
## Architecture
```
┌──────────────────┐ ┌───────────────┐ ┌────────────────────────┐
│ Bubbletea TUI │◀─▶│ provider API │◀─▶│ exec az / gcloud / aws │
│ (pages + keys) │ │ (normalized) │ │ (JSON → structs) │
└──────────────────┘ └───────────────┘ └────────────────────────┘
```
- `cmd/cloudnav` — entrypoint.
- `internal/cmd` — Cobra commands (`tui`, `doctor`, `version`, `ls`, `completion`).
- `internal/provider` — `Provider` interface + Azure/GCP/AWS implementations. Each provider owns its CLI adapter and JSON unmarshaling.
- `internal/cli` — generic subprocess runner with timeout + context.
- `internal/nav` — navigation stack (breadcrumbs, back, context).
- `internal/tui` — Bubbletea model, pages (home/list/detail), keymap, styles.
- `internal/iam` — provisioning of scoped SP / SA / IAM Role with least-privilege presets.
See [`docs/architecture.md`](docs/architecture.md) for the full design.
## Roadmap
See [`ROADMAP.md`](ROADMAP.md). Current phase: **1 — Azure navigation + PIM**.
## Development
```bash
git clone https://github.com/tesserix/cloudnav.git
cd cloudnav
make dev # runs against your currently-logged-in az session
make test
make lint
make build
```
Contributions welcome — read [`CONTRIBUTING.md`](CONTRIBUTING.md) first.
## Security
Found a vulnerability? Please follow the process in [`SECURITY.md`](SECURITY.md) — do not open a public issue.
## License
Apache License 2.0 — see [`LICENSE`](LICENSE).