CLI Authentication

The avsb CLI authenticates with a personal access token (avsb_pat_…): the same credential documented in Personal Access Tokens, and one of the four in Credentials. There are two ways to give it one, and one of them needs no prompt, no browser, and no file on disk.

Create a token

Interactive login

avsb login

You are asked for the token, and nothing else. Script and style languages are read from each experiment on the platform, so the CLI never asks you to pick them.

$ avsb loginPaste your personal access token: ********Token verifiedLogged in to Acme Corp as jane@example.comToken saved in plain text at /Users/jane/.avsb/config.json (file mode 0600).

Options:

Headless login for scripts and CI

Set AVSB_TOKEN and every command uses it. No avsb login step, and nothing written to disk:

export AVSB_TOKEN=avsb_pat_...avsb codegen --project 42

If you would rather save the token to the machine without a prompt, for example when provisioning a container:

avsb login --token "$AVSB_TOKEN" --no-input

Environment variables

Precedence

For the token:

1. --token on avsb login
2. AVSB_TOKEN
3. The saved login in ~/.avsb/config.json
4. The interactive prompt, when prompting is allowed
5. Standard input, when there is no terminal to prompt in: echo "$AVSB_TOKEN" | avsb login reads the token from the pipe, with no masked prompt drawn into your log

For the platform URL:

1. -u, --url on avsb login
2. AVSB_API_URL
3. The URL saved at login
4. https://app.avsb.cloud

AVSB_TOKEN wins over the saved login on purpose, so a CI job cannot pick up a stale token from a cached home directory. avsb whoami prints which of the two is in use.

A GitHub Actions example

- name: Generate flag types  env:    AVSB_TOKEN: ${{ secrets.AVSB_TOKEN }}  run: |    npm install -g @avsbhq/cli    avsb codegen --project 42 --output src/generated/flags.ts

Store the token as an encrypted secret. Give it a name that says where it runs, so you can revoke exactly the right one later.

Where the token is stored

avsb login writes ~/.avsb/config.json and sets the file mode to 0600, which makes it readable and writable by your user only on macOS and Linux. Windows ignores mode bits, so the file inherits whatever permissions its parent folder gives it.

The file holds one entry per organization you have logged in to, which one is active, and the platform URL:

{  "version": 2,  "activeOrgId": "clx1org...",  "logins": [    { "orgId": "clx1org...", "orgName": "Acme Corp", "token": "avsb_pat_..." }  ],  "apiBaseUrl": "https://app.avsb.cloud"}

avsb logout deletes the whole file, including every saved organization.

avsb whoami

Asks the platform who the current token belongs to, then prints the answer next to the local facts:

$ avsb whoamiSigned in  Email: jane@example.com  Organization: Acme Corp  Org ID: clx1org...  Role: DEVELOPER  API URL: https://app.avsb.cloud  Token from: /Users/jane/.avsb/config.json

Token from is either the path to the config file or AVSB_TOKEN environment variable. Use this command when a script behaves differently from your terminal: nine times out of ten they are using different tokens.

avsb whoami also accepts --json (print the result as one JSON document) and --quiet. --quiet prints the result and nothing else: the answer still prints (for avsb whoami, one Email: … style line per field), while progress, headings and blank lines do not. Warnings and errors still go to stderr.

Role is the name of your role in that organization, such as OWNER or DEVELOPER, and --json carries the same name in role.

Organizations

A personal access token belongs to a user, not to one organization, so it usually reaches every organization your account belongs to.

avsb org            # the active organization and where the token came fromavsb org list       # every organization this token can reachavsb org switch     # pick one, interactively

avsb org and avsb org list take the same --json and --quiet flags as avsb whoami. avsb org switch does not; it only takes --no-input.

avsb org switch also takes the organization directly, which is what scripts want:

avsb org switch 42            # by short IDavsb org switch "Acme Corp"   # by nameavsb org switch clx1org...    # by IDavsb org switch 42 --no-input # fail rather than prompt

Without an organization and without a terminal to ask in (CI, a pipe, or --no-input), avsb org switch stops with usage exit code 2 and lists the organizations you can name instead of prompting.

Switching records your choice in ~/.avsb/config.json. Commands that address a project or experiment directly (avsb clone 300015, avsb metrics list --project PRJ-42) resolve the organization from that project, so they work regardless of which one is active.

Two accounts on one machine

Logging in with a token for a different account adds a login rather than replacing one. avsb org list shows both:

$ avsb org listOrganizations  ID  Name  ──  ──────────────────────────────● 41  Acme Corp  42  Beta Inc  -   Client Co  (saved login)  ● = organization commands use now  (saved login) = saved from another token; log in with that token to use it  Change it with `avsb org switch <short id | id | name>`

Rows with a short ID are reachable with the token in use now. A row marked (saved login) came from a different token: switch to it and the CLI uses the token saved with it.

When the wrong credential is pasted

A vs B mints four credentials and only one of them signs a CLI request: a personal access token, which starts with avsb_pat_. The CLI checks that before it makes any request, and names what it got:

• A service token (avsb_svc_) is for organization automation against the REST API, not for the CLI.
• An SDK key (sdk_) is a public identifier your application uses to read flags. It cannot sign in.
• A token starting with the older bare pat_ no longer works. Generate a new one.

Troubleshooting

Every credential problem exits with code 3, so a script can retry or refresh a token without reading the message. See Exit codes for the rest.