System Requirements
No npm login is required to install. Without Bun, the interactive TUI prints install guidance and the CLI remains fully usable. On Windows, use Apollo CLI 0.1.105 or later — earlier releases refuse every saved login there.
Install
apollo upgrade names the apollo release-notes --since <old version> command that lists everything since the release you had. The CLI also tells you when a newer release is out — see Staying up to date.
Authentication
apollo login opens the browser sign-in flow via the Playground; sign in and you’re redirected back automatically.
Other login modes:
Login stores access and refresh tokens in
~/.apollo/credentials.json (mode 600; on Windows, %USERPROFILE%\.apollo\credentials.json, protected by your user profile’s access rules). Normal commands need no additional secrets, and credentials persist across terminal sessions. apollo logout invalidates the remote session and removes the local credential.Profiles
Profiles keep separate credentials for different users or contexts:--profile <name> before any command is a one-command override for automation — it does not change the saved default.
Post-Login Setup
1
Verify your session
--check to also verify service connectivity and authorization, or run apollo doctor for a full end-to-end diagnosis.2
Enable shell integration (recommended)
The install adds this line to your zsh and bash startup files for you (it skips that in CI, or with This lets
APOLLO_NO_SHELL_SETUP=1). Restart your shell to activate it, or add it yourself for any other setup:apollo agent use / import / create drop your shell directly into the agent’s checkout directory.3
Create or import an agent
~/apollo/; use --dir for an intentional other path. Both commands install authoring skill packs for Cursor and Claude Code into the checkout.Staying up to date
The CLI ships often, and it tells you when something falls behind — with the command that fixes it. A newer CLI. Once an hour, after a command finishes, the CLI checks npm for a newer release in the background; no command waits on it. When one is out, plain runs print a line on stderr after the result:AGENTS.md, and schemas come from the runtime its version runs on. When that runtime moves ahead of them, commands that reach it say so:
apollo skills update refreshes them without touching the program, so it’s safe with local changes.
A checkout’s runtime. When the checkout is pinned to an older runtime than the newest released one, commands that reach the runtime offer the upgrade. It’s never enforced: upgrading moves the agent to the new runtime, and a build turn upgrades its program.
--json, the same requests arrive as update, skills_update, and runtime_update fields on the envelope, each with the command to run and a one-sentence message. In the TUI, a newer CLI shows as a toast and a marker in the footer. After any upgrade, apollo release-notes says what changed in the CLI and in the runtime your checkout runs on, and what to do next.
Behind a corporate proxy
Set the proxy the way you would for curl. Every request the CLI and the TUI make, and the update check, then goes through it:https_proxy, http_proxy, no_proxy) work too, and win when both are set. Only HTTP(S) proxies are supported: a bare host:port reads as http://host:port, and any other scheme (socks5://, …) is refused by name rather than silently bypassed.
Uninstall
Next Steps
Command Reference
Full reference for all CLI commands.
Configuration
Checkout structure, config files, and environment variables.