Skip to main content
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, —url AUTH_URL    API base URL
  —type {iam,jwt}      Auth type (default: iam)
  -P, —project AUTH_PROJECT
                        Project ID (IAM only)
  -p, —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:
VariableFallback forPriority
CONTREE_TOKEN--tokenflag > CONTREE_TOKEN > NEBIUS_API_KEY > prompt
NEBIUS_API_KEY--token(see above)
CONTREE_URL--urlflag > env > type-specific default > prompt
CONTREE_PROJECT--projectflag > 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
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