> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt > Use this file to discover all available pages before exploring further. # auth - Configure credentials and profiles Configure authentication tokens and manage profiles. Each profile stores credentials for a different project or environment. ## Examples ```bash theme={null} # 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: | 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): ```bash theme={null} 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: ```bash theme={null} 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
```bash theme={null} 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: ```bash theme={null} # 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 * [Install & Authenticate](../tutorial/installation) – full authentication guide * [Configuration & Profiles](../tutorial/configuration) – config file format and precedence