Skip to main content
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 -f 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):
PathPurpose
auth.iniProfile credentials and settings (created with mode 0600)
cli.iniOptional user-editable defaults for the CLI
cli/sessions/{profile}.dbPer-profile sessions, history, branches, cache
cli/skills.dbInstalled 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):
KeyMaps to flagNotes
log_level--log-levelOne of debug, info, warning, error, critical
output_format-f / --formatOne 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:
KeyRequiredNotes
urlyes for JWT, optional for IAMAPI base URL
typeoptionaljwt (default) or iam
projectIAM onlyProject ID
tokenoptionalAPI 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:
VariableDescription
CONTREE_HOMEData directory (default $XDG_CONFIG_HOME/contree, or ~/.config/contree)
XDG_CONFIG_HOMEXDG base config dir, used to derive the default CONTREE_HOME
CONTREE_PROFILEActive profile name (selects which profile commands use)
CONTREE_SESSIONExplicit session key (overrides auto-generated)
Read only by contree auth (registration-time fallbacks for omitted flags):
VariableUsed 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:
  1. CLI flag (--token, --url, --project) — overrides profile for the current invocation only
  2. Saved profile field
  3. 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:
  1. -p / --profile flag
  2. CONTREE_PROFILE environment variable
  3. profile key in config [DEFAULT] section
  4. Falls back to default
See auth - Configure credentials and profiles for the full auth command reference, or Command Reference for all commands.