auth

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 Nebius environment variable shortcuts:   NEBIUS_API_KEY     used as token fallback during registration   NEBIUS_AI_PROJECT  used as project fallback during IAM registration 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-cli/config.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.studio.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, --project) are not passed, contree auth checks these environment variables before falling back to an interactive prompt:

Variable

Fallback for

Priority

NEBIUS_API_KEY

--token

flag > env > prompt

NEBIUS_AI_PROJECT

--project

flag > env > prompt

If both 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 ls status column

contree auth ls verifies each saved profile against the API with a 2-second timeout and adds a status column.

Possible values:

  • ok – probe succeeded

  • 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

Use contree auth ls --offline when you want to inspect saved profiles without any network traffic.

For automation and agents, prefer:

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

auth remove

Delete a saved profile from the config file.

contree auth remove personal
contree auth rm personal         # alias
contree auth del personal -y     # skip confirmation

If the removed profile was active, the CLI switches to the first remaining profile (or default if none remain).

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

You can also authenticate without the config file:

# Environment variable (avoid in shared environments)
export CONTREE_TOKEN=eyJ...

# Inline flag (per-command, visible in process listings)
contree --token=eyJ... images

See also