pay, subscriptions, customers, invoices, status) runs against the account you’re logged into, not an API key. Log in once and the session persists across terminal restarts.
How it works
agenta login uses a device-code flow, the same pattern GitHub CLI and similar tools use: the terminal and the browser are two different places, so the CLI hands you a short code to confirm in the browser instead of asking for a password on the command line.
1
CLI requests a device code
agenta calls your server and gets back a deviceCode, a short human-readable userCode, and a verificationUrl.2
Browser opens automatically
The CLI opens
verificationUrl in your default browser and prints the same URL and userCode in the terminal, in case it can’t open a browser for you (SSH sessions, headless boxes).3
You confirm in the browser
Sign in and approve the code. Nothing else happens in the browser: no wallet setup, no extra onboarding step, just confirming that this terminal should be allowed to act as you.
4
CLI polls until you approve
agenta polls the server every few seconds for up to 10 minutes. Once you approve, it receives a session token and a refresh token and stores them locally.Usage
If you’re already logged in,
agenta login doesn’t re-authenticate. It tells you to run agenta logout first if you want to switch accounts.Example output
Output
Where the session lives
Login writes a session file to~/.agenta/session.json (mode 0600, readable only by you) containing the session token, refresh token, and the server URL you logged into. It’s plain file storage, not your OS keychain: a short-lived session token doesn’t need biometric protection, and keychain prompts would add friction to every command.
Every command that needs a session (agenta status, agenta pay ..., and so on) reads this file and refreshes the token automatically in the background when it’s close to expiring. You only need to run agenta login again if the refresh token itself has expired or been revoked, in which case the CLI tells you to.
The CLI authenticates with a browser-confirmed session, not an API key. If you need key-based auth for a server or script instead of an interactive login, use the
@agentaos/pay SDK or the REST API directly with an sk_live_/sk_test_ key. See Payment SDK.Logout
Output
Next steps
Status
Confirm your account, wallet, and tool readiness after logging in.
Pay
Create your first checkout from the terminal.