Skip to main content
The xpander CLI authenticates per profile and stores credentials at ~/.xpander/credentials. You can have multiple profiles for different organizations or environments (production, staging, …).

​
xpander login (alias l)

Authenticate via browser. Opens xpander.ai in your default browser, completes the OAuth flow, and writes credentials to the active profile. 
xpander login
xpander login --profile staging
xpander login --new           # force a new profile even if one exists
FlagDescription
--profile <name>Profile name to write credentials to. Defaults to the active profile (or default).
--newCreate a new profile even if one already exists with this name.

​
xpander configure (alias c)

Set up API credentials manually (for environments without a browser, or when you already have an API key). 
xpander configure
xpander configure --key sk-... --org 8d185373-... --profile staging
xpander c --key sk-... --no-validate
FlagDescription
--key <api_key>API key to store. If omitted, the wizard prompts.
--org <organization_id>Organization ID. Optional: auto-detected from the key if omitted.
--profile <name>Profile to write to.
--no-validateSkip credential validation against the cloud (useful when the API is unreachable but you know the key is good).
The wizard:
  1. Stores your API key in the profile.
  2. Validates against xpander.ai (unless --no-validate).
  3. Auto-detects your organization ID.
  4. Writes both to ~/.xpander/credentials.
Output: 
? Enter your Xpander API key: <your-key>
✔ API key validation successful
API key saved to profile "default".
Detecting organization ID...
✔ Organization ID detected: 8d185373-8b24-47a7-8607-3e9036b968bb
Credentials stored at: ~/.xpander/credentials

​
xpander profile

Manage profiles. 
xpander profile --list                    # list all profiles
xpander profile --set-default staging     # set the default profile
xpander profile --new                     # wizard for a new profile
xpander profile --new staging             # create profile named "staging"
xpander profile --edit staging            # edit an existing profile
xpander profile --verify                  # verify the current profile works
xpander profile --verify staging          # verify a specific profile
FlagDescription
--listList all profiles.
--set-default <name>Set a profile as the default.
--new [name]Create a new profile. Without a name, runs an interactive wizard.
--edit <name>Edit an existing profile.
--verify [name]Verify a profile by hitting the API. Without a name, verifies the active profile.
Use --profile <name> on any command to override the active profile for a single call: 
xpander agent list --profile staging
xpander agent deploy my-agent --profile production

​
xpander secrets-sync

Upload your local .env variables to deployed agents as runtime secrets. 
xpander secrets-sync
xpander secrets-sync --profile production
FlagDescription
--profile <n>Profile to use.
This reads .env in the current directory and uploads each KEY=value line to the deployed agent’s secret store. Existing secrets with the same key are overwritten. Use this after xpander agent deploy whenever you change environment-dependent config without rebuilding the container: for example, rotating an external API key.

​
Auth priority

When multiple credential sources are present, the CLI resolves auth in this order:
  1. --api-key on the command line.
  2. XPANDER_API_KEY environment variable.
  3. ~/.xpander/credentials (the active profile).
This lets CI runners override the local profile without touching it.

​
Files and locations

PathPurpose
~/.xpander/credentialsPer-profile credentials (API key, organization ID).
.env (project root)Local env vars. Read by xpander agent dev and uploaded by xpander agent deploy / secrets-sync.