Configuration & Profiles

Profiles let you store credentials for multiple projects or environments and switch between them. This section walks through setting up profiles, switching contexts, and understanding how configuration is resolved.

Creating profiles

Each profile stores a token and API URL for a specific project or environment. When you first ran contree auth, it created a profile called default. Add more with --profile:

contree auth --profile=personal
contree auth --profile=sandbox

Each command prompts for a token securely (no echo), verifies it against the API, and writes it to ~/.config/contree/auth.ini. The resulting config file looks like this:

[DEFAULT]
profile = default

[profile:default]
token = eyJ...
url = https://api.tokenfactory.nebius.com/sandboxes
type = iam
project = project-id-default

[profile:personal]
token = eyJ...
url = https://api.tokenfactory.nebius.com/sandboxes
type = iam
project = project-id-personal

[profile:sandbox]
token = eyJ...
url = https://api.tokenfactory.nebius.com/sandboxes
type = iam
project = project-id-sandbox

Each profile is a [profile:NAME] section with token, url, type, and project keys. The [DEFAULT] section stores the name of the active profile.

Listing profiles

See all saved profiles and which one is active:

contree auth ls

The output shows the profile name, URL, a token hash (first 16 chars of SHA256), active status, and a health check result. auth ls verifies each profile against the API with a 2-second timeout. Possible status values:

ok — token is valid and has the required sandbox permission
timeout — server did not respond in time
error — bad token or network error
offline mode — you passed -O / --offline
no url — the profile has no API URL configured (re-run contree auth)
inactive — token authenticates, but the configured project does not grant the sandbox permission this CLI needs

Skip the network check:

contree auth ls -O

For automation, use structured output:

contree -o json auth ls

Switching profiles

Persistent switch

Change the active profile for all future commands:

contree auth switch personal

Per-command override

Use -p / --profile on any command:

contree -p personal images
contree -p sandbox run -- uname -a

Environment variable

Override for the entire shell session:

export CONTREE_PROFILE=sandbox
contree images        # uses sandbox

Inline token

Pass --token and --url directly:

contree --token=eyJ... --url=https://api.tokenfactory.nebius.com/sandboxes images

Avoid --token on the command line in production — the token is visible in process listings and shell history.

Removing profiles

Delete a profile and its session database:

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

If the removed profile was active, the CLI switches to the first remaining profile.

Profiles and sessions

Each profile has its own session database (~/.config/contree/sessions-{profile}.db), so:

Same profile, same terminal — resumes the existing session
Different profile, same terminal — different session, different data

Switching from default to personal does not affect your default sessions — you can switch back and continue where you left off.

To share a session across profiles (rare), set CONTREE_SESSION:

export CONTREE_SESSION=shared-session

Data storage

All data lives in CONTREE_HOME (default $XDG_CONFIG_HOME/contree, falling back to ~/.config/contree when XDG_CONFIG_HOME is unset):

Path	Purpose
`auth.ini`	Profile credentials and settings (created with mode `0600`)
`cli.ini`	Optional user-editable defaults for the CLI
`cli/sessions/{profile}.db`	Per-profile sessions, history, branches, cache
`cli/skills.db`	Installed agent skill registry

Override with $CONTREE_HOME:

export CONTREE_HOME=/custom/path

`cli.ini`

cli.ini is meant for hand-editing. Create it yourself; the CLI never writes to it. Two kinds of sections are supported:

`[cli]` section: per-flag defaults

Keys here become argparse defaults. Use the argparse dest name (not the flag name):

Key	Maps to flag	Notes
`log_level`	`--log-level`	One of `debug`, `info`, `warning`, `error`, `critical`
`output_format`	`-f` / `--format`	One of the formatter names (`default`, `json`, `json-pretty`, `csv`, `tsv`, `table`)
`editor`	`--editor` (file edit)	Fallback when neither `--editor` nor `$EDITOR` is set; if absent the CLI searches `vim` then `nano` on `PATH` and falls back to `vi`

Example:

[cli]
log_level = debug
output_format = json
editor = nvim

Precedence: CLI flag > environment variable > cli.ini > built-in default. A cli.ini setting always loses to an explicit flag.

`[profile:NAME]` sections: CLI-scoped profiles

cli.ini accepts the same [profile:NAME] sections as auth.ini and supports the same fields:

Key	Required	Notes
`url`	yes for JWT, optional for IAM	API base URL
`type`	optional	`jwt` (default) or `iam`
`project`	IAM only	Project ID
`token`	optional	API bearer token

The two files are merged at load time and auth.ini wins on conflict. What cli.ini is for: profiles (or any field, including token) you want only the contree CLI to see. The CLI merges cli.ini with auth.ini. Other contree-related tooling that talks to the API directly (the SDK, the MCP server) reads only auth.ini. Use cli.ini when you need a profile that should be invisible to those direct-API consumers, or to keep auth.ini minimal and shared. Example, CLI-only profile alongside the shared one:

# ~/.config/contree/auth.ini  (read by CLI + SDK + MCP, mode 0600)
[DEFAULT]
profile = default

[profile:default]
url = https://contree.dev
token = eyJhbGciOi...

# ~/.config/contree/cli.ini  (read only by the CLI)
[profile:cli-sandbox]
url = https://staging.contree.dev
token = eyJhbGciOi...different

The active profile is still selected by the profile key in [DEFAULT] of auth.ini (or by --profile / $CONTREE_PROFILE).

Environment variables

Read at runtime by any command:

Variable	Description
`CONTREE_HOME`	Data directory (default `$XDG_CONFIG_HOME/contree`, or `~/.config/contree`)
`XDG_CONFIG_HOME`	XDG base config dir, used to derive the default `CONTREE_HOME`
`CONTREE_PROFILE`	Active profile name (selects which profile commands use)
`CONTREE_SESSION`	Explicit session key (overrides auto-generated)

Read only by contree auth (registration-time fallbacks for omitted flags):

Variable	Used for
`CONTREE_TOKEN` / `NEBIUS_API_KEY`	`--token`
`CONTREE_URL`	`--url`
`CONTREE_PROJECT` / `NEBIUS_AI_PROJECT`	`--project`

Resolution precedence

For token, URL, and project at runtime:

CLI flag (--token, --url, --project) — overrides profile for the current invocation only
Saved profile field
Built-in default URL for IAM: https://api.tokenfactory.nebius.com/sandboxes

Environment variables are not consulted at runtime; to refresh credentials from environment variables, run contree auth (which reads CONTREE_TOKEN / NEBIUS_API_KEY, CONTREE_URL, and CONTREE_PROJECT / NEBIUS_AI_PROJECT as fallbacks for the corresponding flags). For profiles:

-p / --profile flag
CONTREE_PROFILE environment variable
profile key in config [DEFAULT] section
Falls back to default

See auth - Configure credentials and profiles for the full auth command reference, or Command Reference for all commands.

Get Started

Inference

Observability

Post-training

Data Lab

Sandboxes

Teams & Access Management

Other Capabilities

Integrations

Creating profiles

Listing profiles

Switching profiles

Persistent switch

Per-command override

Environment variable

Inline token

Removing profiles

Profiles and sessions

Data storage

`cli.ini`

`[cli]` section: per-flag defaults

`[profile:NAME]` sections: CLI-scoped profiles

Environment variables

Resolution precedence

​Creating profiles

​Listing profiles

​Switching profiles

​Persistent switch

​Per-command override

​Environment variable

​Inline token

​Removing profiles

​Profiles and sessions

​Data storage

​cli.ini

​[cli] section: per-flag defaults

​[profile:NAME] sections: CLI-scoped profiles

​Environment variables

​Resolution precedence

Creating profiles

Listing profiles

Switching profiles

Persistent switch

Per-command override

Environment variable

Inline token

Removing profiles

Profiles and sessions

Data storage

`cli.ini`

`[cli]` section: per-flag defaults

`[profile:NAME]` sections: CLI-scoped profiles

Environment variables

Resolution precedence