authama

Authentication Access Manager: SSH keys and config, and package-manager / git auth tokens, in one tool.

Two features in a single static binary with no runtime dependencies:

• SSH management (authama ssh …) - profile-based key and config lifecycle: one manifest is the source of truth, and ~/.ssh is reproducible output.
• Auth token management (authama token …) - the credential files Composer, npm, Docker, git and curl read, built from a config that names environment variables, never secrets.

macOS, Linux and Windows are all first-class; OpenSSH is the only requirement for the SSH side. sshmgr, the former name, is no longer built or installed. Coming from sshmgr or auth-token-manager? See the migration guide.

Install

authama is built from source: binary releases are on hold, so there is no download, package-manager or go install channel to use. You need Go (the version src/go.mod names), git and make.

git clone https://github.com/simtabi/authama ~/src/authama
make -C ~/src/authama install    # builds build/<your-os>/authama, then copies it to ~/.local/bin
authama doctor

Updating, shell completion, where per-user state lives, and what became of the binaries published before the history restarted are in docs/installation.md. There is no runtime Docker image; the dev container is for working on authama itself.

Quick start guide and usage

Getting started

init seeds an empty manifest; add a profile and a host before reconcile mints anything:

authama init                      # create ~/.config/authama (dirs, perms, seed files)
authama ssh profile add work
authama ssh host add work gh -H github.com -u git --provider github   # or edit manifest.json
authama ssh host apply work acme-prd-web-00 203.0.113.10 deploy web   # add-or-update from a compact spec
authama ssh import ~/.ssh/config                       # or onboard an existing setup

Usage

SSH - build ~/.ssh from the manifest, and get a key onto its target:

authama ssh reconcile --dry-run   # preview: what would be minted, what would be written
authama ssh reconcile             # build ~/.ssh from the manifest
authama ssh config check          # confirm the file matches the manifest (exit != 0 on drift)
authama ssh deploy work_gh-ed25519    # ssh-copy-id, gh, glab, a REST API, or manual
authama ssh validate                  # every keypair parses and the halves match

Auth tokens:

authama token init                # a starter tokens.json (env var names, no secrets)
GH_TOKEN="$(op read op://Private/GitHub/token)" authama token apply   # write auth.json, .npmrc, …
authama token set --target npm --server registry.npmjs.org        # or one token, from a hidden prompt
authama token list                # what is installed, secrets masked
authama token show npm registry.npmjs.org   # one entry in full
authama token status              # which config, which files, which variables are missing
authama token audit               # owner-only modes, .gitignore coverage

Both:

authama doctor                    # SSH health and token-file modes; --fix repairs modes and syncs VM hosts
authama ssh vm sync --dry-run     # keep VM hosts matching their VMs (--install-schedule: daily)
authama ssh key reserve docker-tunnel --for devbox   # keep a loose key for later; doctor stops warning
authama                           # on a terminal: the web UI on this machine, as authama serve
authama serve                     # a web UI on this machine, with previewed changes
authama ssh help deploy           # help at any level: authama help, authama auth help set
authama history                   # every change made, SSH or token
authama events --since 24h        # every change to a tracked file, by anyone
authama man ~/.local/share/man/man1   # manual pages: man authama-ssh-deploy

The full walkthrough is in Getting started; everything else is in the documentation index.

Documentation

Guides

• Installation — install paths, requirements, and where per-user state lives.
• Getting started — first run, from init to a deployed key.
• Configuration — the manifest, profiles, hosts, .env, environment variables.
• Architecture — packages, key flows, and why the layout is what it is.
• Migration — from sshmgr 3.x and from auth-token-manager, with a feature-parity table.
• Release — the tag-driven GoReleaser flow.

Reference

• Command reference — every command and subcommand with its flags, aliases and examples, generated from the binary (a test keeps it current), plus a "which command do I want" table.
• Feature catalog — every command, what it does, and how it is tested.
• token — auth tokens: apply, set, list, show, status, copy, delete, audit, import; per tool: Composer, npm, Docker, git, netrc, PyPI, Cargo, RubyGems, Gradle, Maven, Yarn Berry, Helm, GitHub CLI.
• doctor — what it checks (SSH and token files), --fix, --json, --strict.
• deploy — installing a public key on its target.
• checklist — where each key and token is used, and what is left to rotate or revoke it; choosing several keys to rotate, revoke or delete.
• providers — the adapter catalog and how to extend it.
• VPS keys — cloud account keys and server keys.
• Key lifecycle — a key's lifetime, rotation, regeneration and revocation, in one place.
• Repair and factory reset — fix a broken home, ~/.ssh modes and config, and token file modes; reset without deleting anything.
• Owner binding — a PIN for secrets and destructive changes, and a seal that notices outside edits and a home copied elsewhere.
• rotate — zero-downtime staged rotation and rollback.
• expiry — rotation age and scheduled reminders.
• knownhosts — pinning host keys into the trust store.
• git — checkouts' GitHub remotes in profile SSH, plain SSH or HTTPS mode.
• vm — local VMs as hosts, addressed through their hypervisor; configuring hypervisors, vm sync, vm adopt-key, keeping a key for later (key reserve).
• export — authama export <list>: any list (hosts, keys, profiles, tokens, history, events, snapshots, deployments), filtered, with the columns you choose, in nine formats; and a flat ssh_config, a Termius CSV, or your hosts for Windows Terminal, iTerm2, PuTTY, Remmina or any CSV importer.
• net — reachability and VPN-gated hosts.
• validate — keypair integrity checks.
• bundle — encrypted backup and restore.
• history — every change authama has made, filtered by host, profile or key.
• events — every change seen to a file under ~/.ssh, the config home or a token file, by anyone.
• man — a manual page for every command, and the layout every --help shares.
• serve — the web UI: overview, hosts, keys, snapshots, auth tokens and history in a browser, with previewed changes.
• recover — break-glass when you are locked out.
• tui — the terminal menu, removed: where each of its entries went.

Recipes

• Add or update many hosts at once — host apply with <alias> <host> <user> [role] lines, re-runnable.
• Two GitHub accounts on one machine — one hostname, two identities, neither able to act as the other.
• Keep keys in 1Password — private keys generated and rotated inside a vault; only the .pub on disk.
• Use a GitHub machine user — one bot key with read access to every org repo, rotated in one command.
• Group profiles into categories — internal, clients, others: one directory and one config file each.
• Keep your keys in a directory of your choosing — move ~/.ssh/profiles/ to ~/.ssh/keys/ or any name, keys and config together.
• Switch checkouts to profile SSH — each owner's own key, every URL proven before it is written.
• Use a local VM as a devbox — reach a VM by name whatever its IP, and point Docker at it.
• Import your hosts into Termius — every host with its user, then termius keys to paste each key into Termius's Keychain (the CSV carries no keys).
• Reach a server through Cloudflare Access — ssh <alias> through cloudflared, with no SSH port open to the internet.
• Onboard an existing ~/.ssh — bring a hand-built setup under management without regenerating anything.
• Rotate a key with no downtime — stage, verify, commit; and how to step back.
• Rotate or repair many keys at once — a category or everything in one batch, and rebuilding .pub files.
• Manage SSH from the browser — preview a change before it is written, and watch a deploy or rotation run.
• Work against a sandbox — exercise every verb without touching your real ~/.ssh.
• Back up, and restore onto a new machine — the only path that recovers the same keys.
• Recover from a locked-out server — break-glass with no working SSH.
• Run it in CI — non-interactive, sandboxed, failing loudly.
• Develop in a container — make docker-shell, with a scoped home so tokens never reach your real files.

Community

Contributing · Security policy · Code of conduct · Changelog

License

MIT © Simtabi LLC — see LICENSE.