Authenticate

Sign in with cua auth login, see who is signed in, and sign out.

One sign-in covers the CLI, the SDK, cua daemon and the Cua Spaces app, which share one credential store. Local sandboxes need no sign-in.

Sign in#

cua auth login              # browser (PKCE, loopback redirect)
cua auth login --remote     # device code, for SSH sessions
cua auth whoami             # who is signed in, with plan and teams
cua auth status             # session and expiry, no network
cua auth logout             # revoke and remove the session

After an interactive login, cua auth login offers to set up your AI coding agents (the cua skills plus the cua MCP server). These flags control the offer: --agents claude,codex, --yes, --skills-only, --mcp-only and --no-onboarding. Answering never is remembered in ~/.cua/config. Tokens refresh automatically and are never printed.

CUA_CREDENTIAL_STORE=file or keychain picks the store. A build from source looks like a new app to the Keychain every time you rebuild it, so it uses the file and never asks for Keychain access.

Older versions kept the session, this machine's key and the other secrets under the service run.cua.ai (staging.run.cua.ai for staging). The first cua that reads them after you update moves each item to ai.cua.session, checks the new item and then deletes the old one, so you stay signed in. A cua signed by Cua does this without a password prompt, and so does every later update of it. If macOS would have to ask (the item was created by a program the update does not trust), cua leaves the old item as it is. Run cua auth keychain --prompt in a terminal once and choose Always Allow, or sign in again. cua auth logout removes both the new and the old items.

On macOS, cua never waits on a Keychain dialog it cannot show. In a terminal, it lets macOS ask for access. Without a terminal (an agent, a script or a service), it fails within seconds with a message instead of hanging. That includes the case where a dialog is already open on the Mac's screen and macOS holds the read behind it. Answer the dialog, or run cua auth keychain --prompt in a terminal once and choose Always Allow. CUA_KEYCHAIN_NONINTERACTIVE=1 turns prompts off, 0 allows them without a terminal, and CUA_KEYCHAIN_TIMEOUT_SECS (default 5) sets how many seconds a call may take.

Use the staging environment#

CUA_ENV=staging points the CLI, the SDK, cua daemon and the Cua Spaces app at Cua's staging deployment, which exists for testing Cua itself. Unset or prod means production. Any other value makes cua exit with code 2 instead of falling back to production.

export CUA_ENV=staging
cua auth login --remote     # device code against the staging realm
cua auth status             # starts with "Environment: staging (...)"

Each environment has its own session, host enrollment, Spaces registry and daemon. Signing in to staging never replaces or sends your production session, and the other way round. Usage telemetry follows the environment too: staging events go to the staging PostHog project, never to production's. CUA_POSTHOG_KEY overrides the project key, and CUA_TELEMETRY_ENDPOINT overrides the ingest URL.

Released builds of cua and the Cua Spaces app, beta versions included, use production when CUA_ENV is unset. Set CUA_ENV=staging to use staging.

To open the macOS app against staging, quit the production app first, then launch it with the variable set:

open -n --env CUA_ENV=staging -a "Cua Spaces"

The host service (cua host setup) has one name on each machine, so pair a staging host on a separate machine or VM.

Other variables (CUA_AUTH_FLOW, CUA_NO_BROWSER and more) are listed in the CLI reference.