auth - Configure credentials and profiles

Configure authentication tokens and manage profiles. Each profile stores credentials for a different project or environment.

Examples

# Save a token (secure prompt, no echo)
contree auth

# Save to a named profile
contree auth --profile=personal

# Force overwrite existing profile
contree auth -y

# List all profiles and probe whether they work
contree auth ls

# Structured output for scripts and agents
contree -f json auth ls

# List profiles without network probes
contree auth ls --offline

# Switch active profile
contree auth switch personal

# Remove a profile
contree auth remove personal
contree auth rm personal -y

Help output

$ contree auth --help usage: contree auth [-h] [--token AUTH_TOKEN] [-u AUTH_URL] [--type {iam,jwt}] [-P AUTH_PROJECT]                     [-p PROFILE] [-y]                     {list,ls,profiles,switch,remove,rm,del} ... Configure authentication credentials. Validates a token against the API (GET /v1/whoami) and saves it to the config file under the specified profile. The token is prompted securely via getpass if --token is not provided. Supports two auth types:   iam (default) — bearer token + project ID, default URL provided   jwt (legacy)  — bearer token only, URL must be specified Environment variable fallbacks during registration:   CONTREE_TOKEN / NEBIUS_API_KEY     used when --token is omitted   CONTREE_URL                        used when --url is omitted   CONTREE_PROJECT / NEBIUS_AI_PROJECT used when --project is omitted (IAM) Other commands ignore these variables; only ``contree auth`` reads them. ``CONTREE_PROFILE`` selects the profile for any command. Subcommands:   profiles    List saved profiles (* marks active)   switch NAME Switch the active profile positional arguments:   {list,ls,profiles,switch,remove,rm,del}     list (ls, profiles)                         List saved profiles     switch              Switch active profile     remove (rm, del)    Remove a saved profile options:   -h, --help            show this help message and exit   --token AUTH_TOKEN    API token (prompted if omitted)   -u AUTH_URL, --url AUTH_URL                         API base URL   --type {iam,jwt}      Auth type (default: iam)   -P AUTH_PROJECT, --project AUTH_PROJECT                         Project ID (IAM only)   -p PROFILE, --profile PROFILE                         Profile name (default: default)   -y, --force           Overwrite existing profile without confirmation for coding agents:   `auth` verifies token with /v1/whoami before writing config   mutates local config file and may prompt for token if omitted   use `auth profiles` for read-only profile discovery agent note:   Before using this command in an automated workflow, read:     contree agent

Behavior

When you run contree auth, the CLI:

  1. Prompts for the token securely via getpass (no echo, not stored in shell history)

  2. Prompts for the project ID

  3. Verifies the token with the API (GET /v1/whoami)

  4. Writes credentials to ~/.config/contree/auth.ini

  5. If the profile already exists, prompts for confirmation (use -y to skip)

Flags

  • --token — API token (prompted securely if omitted)

  • --url — API base URL (default: https://api.tokenfactory.nebius.com/sandboxes)

  • --project — Project ID (prompted if omitted)

  • --profile — Profile name (default: default)

  • -y / --force — Overwrite existing profile without confirmation

Environment variable shortcuts

When CLI flags (--token, --url, --project) are not passed, contree auth checks these environment variables before falling back to an interactive prompt:

Variable

Fallback for

Priority

CONTREE_TOKEN

--token

flag > CONTREE_TOKEN > NEBIUS_API_KEY > prompt

NEBIUS_API_KEY

--token

(see above)

CONTREE_URL

--url

flag > env > type-specific default > prompt

CONTREE_PROJECT

--project

flag > CONTREE_PROJECT > NEBIUS_AI_PROJECT > prompt

NEBIUS_AI_PROJECT

--project

(see above)

These variables are read only during contree auth. Other commands ignore them and read credentials strictly from the saved profile.

If the relevant variables are set, contree auth runs fully non-interactively (no prompts):

export NEBIUS_API_KEY=eyJ...
export NEBIUS_AI_PROJECT=your-project-id
contree auth -y      # no prompts, saves immediately

auth list

contree auth list (alias auth ls, profiles) prints every saved profile from auth.ini and verifies each one against the API with a 2-second timeout, adding a status column that tells you at a glance which profiles are usable. Pass --offline to suppress the probe entirely when you only want to inspect what is saved locally.

$ contree auth list --help usage: contree auth list [-h] [-O] List configured local profiles and active marker. options:   -h, --help     show this help message and exit   -O, --offline  Do not probe /v1/whoami; mark all profile statuses as offline for coding agents: read-only command

Possible status values:

  • ok – probe succeeded and the token has the list permission

  • inactive – probe succeeded but the token lacks the list permission, meaning sandboxes are disabled on this project

  • timeout – probe did not complete within 2 seconds

  • error – probe failed for another reason, such as a bad token or another network/API error

  • offline – you passed --offline, so no probe was attempted

For automation and agents, prefer:

contree -f json auth ls
contree -f json auth ls --offline

auth switch

contree auth switch NAME rewrites the active pointer in auth.ini so subsequent commands resolve credentials from that profile. The profile must already exist (created by contree auth --profile=NAME). Switching does not touch token data, so it is safe to run as often as you like to bounce between projects.

$ contree auth switch --help usage: contree auth switch [-h] profile_name Set [DEFAULT] profile in local config file. positional arguments:   profile_name  Profile to activate options:   -h, --help    show this help message and exit for coding agents: mutates local config state

auth remove

contree auth remove NAME (aliases rm, del) deletes the profile from auth.ini and removes its per-profile session database (sessions-NAME.db). If the deleted profile was the active one, the CLI promotes the first remaining profile to active (or falls back to default if none remain). Confirmation is required unless -y is passed.

$ contree auth remove --help usage: contree auth remove [-h] [-y] profile_name Delete a profile section from config. positional arguments:   profile_name  Profile to remove options:   -h, --help    show this help message and exit   -y, --force   Do not ask for confirmation for coding agents: mutates local config state 
contree auth remove personal
contree auth rm personal         # alias
contree auth del personal -y     # skip confirmation

Warning

Avoid --token=eyJ... on the command line — the token is visible in process listings (ps) and shell history. Omit --token to use the secure prompt instead.

Alternative authentication

Runtime commands always read credentials from the saved profile. To authenticate without an interactive auth flow, either:

# 1. Bootstrap the profile non-interactively from environment vars
export CONTREE_TOKEN=eyJ...
export CONTREE_URL=https://api.tokenfactory.nebius.com/sandboxes
contree auth -y --type jwt
contree images

# 2. Or pass the token inline per-command (visible in process listings)
contree --token=eyJ... images

Setting CONTREE_TOKEN alone (without first running contree auth) will not authenticate runtime commands.

See also