> ## 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.

# 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`:

```bash theme={null}
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:

```ini theme={null}
[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:

```bash theme={null}
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:

```bash theme={null}
contree auth ls -O
```

For automation, use structured output:

```bash theme={null}
contree -f json auth ls
```

## Switching profiles

### Persistent switch

Change the active profile for all future commands:

```bash theme={null}
contree auth switch personal
```

### Per-command override

Use `-p` / `--profile` on any command:

```bash theme={null}
contree -p personal images
contree -p sandbox run -- uname -a
```

### Environment variable

Override for the entire shell session:

```bash theme={null}
export CONTREE_PROFILE=sandbox
contree images        # uses sandbox
```

### Inline token

Pass `--token` and `--url` directly:

```bash theme={null}
contree --token=eyJ... --url=https://api.tokenfactory.nebius.com/sandboxes images
```

<Warning>
  Avoid `--token` on the command line in production — the token is
  visible in process listings and shell history.
</Warning>

## Removing profiles

Delete a profile and its session database:

```bash theme={null}
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.

<Tip>
  To share a session across profiles (rare), set `CONTREE_SESSION`:

  ```bash theme={null}
  export CONTREE_SESSION=shared-session
  ```
</Tip>

## 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`:

```bash theme={null}
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:

```ini theme={null}
[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:

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

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

```ini theme={null}
# ~/.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:

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](../commands/auth) for the full auth command reference, or
[Command Reference](../commands/index) for all commands.