Skip to main content
Profiles let you store multiple configurations and quickly switch between them. Each profile saves an access token, instance, workspace, and branch — so you can target different environments without re-authenticating.
Working in a dedicated project directory? Pin it to a profile with a project-local profile.yaml so commands can’t accidentally target the wrong workspace — without passing -p on every command.

​
Profile Wizard

The profile wizard provides a step-by-step, interactive setup using an access token instead of browser-based login. This is useful for CI/CD environments, self-hosted instances, or when you prefer token-based auth.
1

Enter your access token

You’ll be prompted to enter your Xano access token (input is hidden for security).You can generate an access token from your Xano account settings under API Access.
2

Select your instance

The CLI fetches all instances associated with your account. Choose the one you want to work with.
? Select an instance:
❯ My Production Instance (us-east-1)
  My Staging Instance (eu-west-1)
3

Name your profile

Give this profile a name. This lets you maintain multiple profiles for different environments.
? Profile name: (default)
4

Select a workspace

Choose a workspace from your instance, or skip to configure later.
? Select a workspace (or skip to use default):
❯ (Skip workspace)
  My App Backend (123)
  Marketing Site API (456)
5

Select a branch

If you selected a workspace and it has more than one branch, you’ll be asked to choose a branch. Skip to use the live branch.
? Select a branch:
❯ (Skip and use live branch)
  v1
  v2-development
The profile is saved and set as your default. You can create additional profiles to quickly switch between workspaces, branches, or instances.

​
Wizard for Other Environments

For self-hosted or beta environments, pass the -o flag: You can also pre-set the profile name: If your instance uses a self-signed TLS certificate, add --insecure (-k):

​
List Profiles

Add -d for full details including origin URLs, workspace IDs, and masked tokens:

​
Create a Profile Manually

For scripting or CI/CD, create a profile directly without the interactive wizard:
FlagDescription
-tAccess token (required)
-iInstance origin URL (required)
-aAccount origin URL (for self-hosted)
-wWorkspace ID
-bBranch label
-k, --insecureSkip TLS certificate verification (for self-signed certs)
--defaultSet as the default profile

​
Edit a Profile

Update any field on an existing profile: To clear a field, use the corresponding --remove-* flag: You can also enable or disable insecure mode (self-signed certificate support) on an existing profile: When a profile has insecure mode enabled, all commands using that profile automatically skip TLS certificate verification.

​
Get Default Profile

Print the name of the current default profile:

​
Switch Default Profile

​
Verify Profile

Check that your profile is configured correctly: This calls the Xano API and returns a summary of your current setup — CLI version, account details, instance, workspace, and branch. Use -o json for the full JSON response.
Output the access token for the default profile (useful for piping to other commands):
Output the workspace ID for the default profile:

​
Change Workspace Interactively

Switch the workspace on a profile by selecting from a list of available workspaces: To target a specific profile:

​
Delete a Profile

Add -f to skip the confirmation prompt.

​
Using a Profile for a Single Command

Override the default profile for any command with -p: You can also set the XANO_PROFILE environment variable:
To pin a profile for an entire project directory instead of per command, use a project-local profile.yaml. The -p flag and XANO_PROFILE variable always take precedence over it.

​
Project-local Profile

Pin a project directory to a specific profile by adding a profile.yaml file at its root. Any command run inside the project automatically uses the pinned profile — preventing accidental pushes to the wrong workspace when you forget -p. The CLI discovers profile.yaml by searching the current directory and walking up through parent directories (the same way Git locates .git).
profile.yaml contains no secrets. It references a profile by name — the access token always stays in ~/.xano/credentials.yaml. An access_token key in profile.yaml is rejected.

​
Generate one with xano profile use

This writes a self-documenting profile.yaml — every overridable field is included as a commented example, so you can edit it without consulting the docs — and offers to add it to .gitignore, skipping that prompt when the file is already ignored.
FlagDescription
-w, --workspaceOverride the workspace for this project
-b, --branchOverride the branch for this project
-i, --instance_originOverride the instance origin URL
-a, --account_originOverride the account origin URL
--gitignore / --no-gitignoreAdd (or skip adding) profile.yaml to .gitignore without prompting
The generated file looks like this: 
# Xano project-local profile — pins this project to a profile in ~/.xano/credentials.yaml.
# No secrets here: the access token always comes from credentials.yaml.
# Precedence: an explicit -p/--profile or XANO_PROFILE overrides this file entirely.

# Profile to use (a profile name from ~/.xano/credentials.yaml):
profile: staging

# Optional per-project overrides — uncomment and edit any you need:
workspace: 110
# instance_origin: https://your-instance.xano.io
# account_origin: https://app.xano.com
# branch: main

​
Active-profile banner

When a profile.yaml is in effect, every command prints the active target so you always know what you’re pointed at: 
Using profile 'staging' (workspace 110) · profile.yaml
This banner is suppressed when you pass --output json.

​
Selection precedence

The CLI resolves which profile to use in this order:
  1. -p, --profile flag
  2. XANO_PROFILE environment variable
  3. profile.yaml (profile: field, plus any field overrides)
  4. The default profile in ~/.xano/credentials.yaml
An explicit -p/--profile flag or XANO_PROFILE variable ignores profile.yaml entirely.
The credential-management commands — xano profile edit, xano profile me, and xano profile workspace set — write to credentials.yaml and deliberately ignore profile.yaml, so a project pin can’t redirect them.