Setting the file. One moment.
Subchapter 28.1
references/ax-profiles.mdMarkdown4 KBView on GitHub
Consult this when authentication fails (401, missing profile, missing API key). Do NOT run these checks proactively.
Use this when there is no profile, or a profile has incorrect settings (wrong API key, wrong region, etc.).
ax profiles showLook at the output to understand what’s configured:
API Key: (not set) or missing → key needs to be created/updated401 Unauthorized → key is wrong or expiredIf a profile exists but one or more settings are wrong, patch only what’s broken.
Never pass a raw API key value as a flag. Always reference it via the ARIZE_API_KEY environment variable. If the variable is not already set in the shell, instruct the user to set it first, then run the command:
# If ARIZE_API_KEY is already exported in the shell:
ax profiles update --api-key $ARIZE_API_KEY
# Fix the region (no secret involved — safe to run directly)
ax profiles update --region us-east-1b
# Fix both at once
ax profiles update --api-key $ARIZE_API_KEY --region us-east-1bupdate only changes the fields you specify — all other settings are preserved. If no profile name is given, the active profile is updated.
If no profile exists, or if the existing profile needs to point to a completely different setup (different org, different region):
Always reference the key via $ARIZE_API_KEY, never inline a raw value.
# Requires ARIZE_API_KEY to be exported in the shell first
ax profiles create --api-key $ARIZE_API_KEY
# Create with a region
ax profiles create --api-key $ARIZE_API_KEY --region us-east-1b
# Create a named profile
ax profiles create work --api-key $ARIZE_API_KEY --region us-east-1bTo use a named profile with any ax command, add -p NAME:
ax spans export PROJECT -p workNever ask the user to paste their API key into the chat. Never log, echo, or display an API key value.
If ARIZE_API_KEY is not already set, instruct the user to export it in their shell:
export ARIZE_API_KEY="..." # user pastes their key here in their own terminalThey can find their key at https://app.arize.com/admin (opens in a new tab) > API Keys. Recommend they create a scoped service key (not a personal user key) — service keys are not tied to an individual account and are safer for programmatic use. Keys are space-scoped — make sure they copy the key for the correct space.
Once the user confirms the variable is set, proceed with ax profiles create --api-key $ARIZE_API_KEY or ax profiles update --api-key $ARIZE_API_KEY as described above.
After any create or update:
ax profiles showConfirm the API key and region are correct, then retry the original command.
There is no profile flag for space. Save it as an environment variable — accepts a space name (e.g., my-workspace) or a base64 space ID (e.g., U3BhY2U6...). Find yours with ax spaces list -o json.
macOS/Linux — add to ~/.zshrc or ~/.bashrc:
export ARIZE_SPACE="my-workspace" # name or base64 IDThen source ~/.zshrc (or restart terminal).
Windows (PowerShell):
[System.Environment]::SetEnvironmentVariable('ARIZE_SPACE', 'my-workspace', 'User')Restart terminal for it to take effect.
At the end of the session, if the user manually provided any credentials during this conversation and those values were NOT already loaded from a saved profile or environment variable, offer to save them.
Skip this entirely if:
ARIZE_API_KEY env varARIZE_SPACE env varHow to offer: Use AskQuestion: “Would you like to save your Arize credentials so you don’t have to enter them next time?” with options "Yes, save them" / "No thanks".
If the user says yes:
API key — Run ax profiles show to check the current state. Then run ax profiles create --api-key $ARIZE_API_KEY or ax profiles update --api-key $ARIZE_API_KEY (the key must already be exported as an env var — never pass a raw key value).
Space — See the Space section above to persist it as an environment variable.