# Configuration

> Where div finds its key, its control plane and its project — flags, the environment, divergent.json and the settings file, in that order.

`div` reads three things before it does anything: the API key, the control plane's address, and the project a run belongs to. Each can come from four places, and the first one that has it wins.

## Order of precedence

| Where | What it can set |
| --- | --- |
| flags | `--token`, `--api-url`, `--project` |
| the environment | `DIVERGENT_API_KEY`, `DIVERGENT_API_URL`, `DIVERGENT_PROJECT` |
| `divergent.json` | `project`, `volume`, `api_url` — in this directory, or the nearest one above it |
| `~/.config/divergent/config.json` | `token`, `api_url`, `project` — written by `div login` |

With none of them, the API is `https://api.divergentlabs.xyz` and the project is this directory's name. With no key anywhere, every command but `div login` stops and says how to get one, and exits 2.

`DIVERGENT_API_KEY= div whoami` falls through to the saved key — a variable set to nothing counts as unset. `DIVERGENT_TOKEN` is read as well, after `DIVERGENT_API_KEY`.

`div whoami` prints where the key was found, which is usually the answer when a command is talking to the wrong org.

## divergent.json

A directory can say which project its runs belong to, and which volume its code is shipped to. `div` looks in this directory, then each one above it, and reads the nearest file it finds.

```json
{ "project": "very-cool-classifier", "volume": "contracts-v3" }
```

| Field | What it does |
| --- | --- |
| `project` | the project runs from here belong to, instead of this directory's name |
| `volume` | where [`div run`](https://docs.divergentlabs.xyz/compute/cli/run.md) ships the code, instead of `<project>-code` |
| `api_url` | the control plane to talk to, instead of `https://api.divergentlabs.xyz` |

Commit it: it holds nothing secret.

## The settings file

`~/.config/divergent/config.json`, or `$XDG_CONFIG_HOME/divergent/config.json` when that is set. [`div login`](https://docs.divergentlabs.xyz/compute/cli/login.md) writes it, readable only by its owner:

```json
{
  "token": "dv_live_…"
}
```

`api_url` is there only when the login was against a control plane other than production. `div login` replaces the key and keeps every other field. A file that is not JSON is treated as absent.

## Project names

Whatever names the project is slugified the same way the API does it: lowercased, anything that is not a letter or digit becomes one hyphen, and it is cut at 63 characters. `My Classifier (v2)` is `my-classifier-v2`. A name that slugifies to nothing is refused.