@aromo/cli

Command-line client for the Aromo headless API.

# Install (once published)
npm install -g @aromo/cli

# Authenticate this device
aromo login

# Verify
aromo whoami

# Diagnostic
aromo doctor

Commands

| Command | What it does | |---|---| | aromo login | RFC 8628 device flow against /auth/device/{code,token}. Opens a browser to the verification URL; polls until the user approves; stores the issued API key in the OS keychain (or a 0600 file when no keychain is available). | | aromo logout [--revoke] | Clears the cached credentials for the current API URL. By default the key remains valid on the server (other machines may still use it); --revoke also deletes the key server-side. | | aromo whoami [--all] | Prints the active credential and the backend storing it. --all lists every credential the CLI knows about across hosts. | | aromo doctor | Preflight checks: Node version, API URL, URL scheme (warns on http:// against non-local hosts), credential storage backend, credential presence, /health/live reachability. |

Configuration

| Env var | Purpose | Default | |---|---|---| | AROMO_API_URL | Base URL of the Aromo API (must include /api/v1). | https://api.aromo.ai/api/v1 | | AROMO_ADMIN_URL | Used only as a defensive fallback if the device-code response omits verification_uri. | https://admin.aromo.ai/dev/activate | | AROMO_CONFIG_DIR | Override the config directory (config.json + credentials.json). | $XDG_CONFIG_HOME/aromo on Linux/macOS, %APPDATA%\aromo on Windows | | AROMO_CREDS_FILE | Override the credentials file path only. | <config dir>/credentials.json | | AROMO_CREDS_BACKEND | Force keyring or file. Default: probe keyring, fall back to file. Useful for CI runners + portable bundles. | auto | | AROMO_DEBUG | Set to anything to print stack traces on errors. | unset |

How aromo login works

The CLI uses RFC 8628 — OAuth 2.0 Device Authorization Grant, the same flow gh auth login and npm login use. In short:

1. POST /auth/device/code — server returns a device_code (long, secret), a user_code (short, human-typeable), and a verification URL.
2. CLI shows the URL + user_code and opens the browser if possible.
3. CLI polls POST /auth/device/token every few seconds.
4. User signs in to the dev portal, pastes the user_code at /dev/activate, and approves.
5. CLI's next poll returns { api_key, api_key_id, client_id, user_id } — written to the credentials file.

The device_code substitutes for a client secret. No CLI-side keypair, no localhost redirect port — works fine over SSH or in a headless container.

Credential storage

The CLI uses the OS keychain by default, falling back to a 0600 file on hosts without a keychain available.

| Platform | Backend | Where | |---|---|---| | macOS | Keychain | service aromo-cli, account = API URL | | Windows | Credential Manager | target aromo-cli, username = API URL | | Linux (with libsecret) | libsecret | collection default, service aromo-cli | | Headless Linux / WSL / CI without keychain | File | ~/.config/aromo/credentials.json (mode 0600), keyed by API URL |

Either backend is keyed by API URL so you can be logged into prod + staging + a local dev server simultaneously. aromo doctor reports which backend is active and aromo whoami shows it under "Storage".

Migration is automatic and one-way: if you start out on the file backend (e.g. you installed before keychain support landed) and the keychain later becomes available, the next aromo login migrates the credential into the keychain and removes the file copy.

To force a backend (CI portability, headless boxes that have a broken libsecret install, etc.) set AROMO_CREDS_BACKEND=file or AROMO_CREDS_BACKEND=keyring.

Development

npm install
npm run dev -- login            # run directly from TypeScript
npm run build                   # tsc → dist/
npm test                        # node --test on src/**/*.test.ts