# CLI configuration

Where tanomis keeps its configuration, how contexts and credentials are stored, and the environment variables and flags that override them.

`tanomis` resolves its configuration from three layers: flags on the command, environment variables,
and a config file with named contexts. Flags win, then the environment, then the file.

## The config file

`tanomis` searches from the working directory upward for `.tanomis.yaml`, then `.cog.yaml`
at each level. If no repo config exists, it uses `~/.config/tanomis/config.yaml`, falling
back to `~/.config/cog/config.yaml` when the new file is absent. `--config PATH` selects
an explicit file. Configuration and cached credentials migrate to the new directory
when each is next written; explicit file paths are respected. `tanomis login` creates a context.

```yaml title="~/.config/tanomis/config.yaml"
current-context: saas
contexts:
  saas:
    auth-mode: oidc
    # endpoints discovered from the hosted console at login; no secret here
```

A context holds the environment's endpoints, its authentication mode, and the selected workspace.
It never holds a secret: cached credentials live separately, per context, and `tanomis logout` clears
them while keeping the context.

## Contexts

```bash title="Terminal"
tanomis config current-context
tanomis config use-context staging
tanomis config view
tanomis config delete-context old
```

`view` prints the effective configuration after flags and environment are applied, which is the
fastest way to see which environment a command will hit. Create a context by logging in to that
environment with `tanomis login --console URL --name NAME`.

## Authentication modes

| Mode | Used for |
|---|---|
| `oidc` | The hosted device-authorization login a person completes in a browser. The hosted default. |
| `none` | Environments with no authentication; not applicable to hosted Tanomis. |

For unattended use, `tanomis` exchanges an automation client's ID and secret for a token when
`TANOMIS_API_URL`, `TANOMIS_CLIENT_ID`, and `TANOMIS_CLIENT_SECRET` are set; no login mode is involved.
See [Automation credentials](/guides/deploy/automation-credentials).

For human logins, access tokens are short-lived. Before an authenticated command, `tanomis` reuses a valid token or
refreshes it; if the refresh grant is gone, the command stops and asks you to `tanomis login` again.

## Environment variables

| Variable | Effect |
|---|---|
| `TANOMIS_API_URL` | Public platform API origin for machine authentication and discovery. |
| `TANOMIS_CLIENT_ID` | Organization automation client ID. Use with `TANOMIS_CLIENT_SECRET`. |
| `TANOMIS_CLIENT_SECRET` | Automation client secret, injected from a secret manager. Never saved by machine login. |
| `TANOMIS_CA_BUNDLE` | CA bundle path for deployments with a private certificate authority. |
| `TANOMIS_TENANT` | Default for `--tenant` on tenant-scoped commands. |
| `TANOMIS_OUTPUT` | Default for `--output`: `table` or `json`. |

Each `TANOMIS_*` CLI setting accepts its former `COG_*` name as a fallback when the
new name is unset; using an old name emits one deprecation notice per process.

Other `TANOMIS_*` variables exist for internal endpoint and identity plumbing and are not part of the
public contract.

With a human login, deploy and session-run commands refuse a `--tenant` that differs from the selected workspace, so
the variable and the selection must agree. Machine authentication ignores cached human workspace
and support context; choose an organization tenant explicitly, or let the sole/default ready
tenant be selected.

## Global flags

| Flag | Effect |
|---|---|
| `--context NAME` | Use a context for this command without changing the current one. |
| `--tenant ID` | Tenant for tenant-scoped commands. Must match the selected workspace where one is selected. |
| `-o, --output table\|json` | Output format. Use `json` in scripts. |
| `--config PATH` | Config file path. |
| `--verbose` | Verbose output. |

Every command page in the [CLI reference](/cli) lists these under Global flags.

## Where to go next

- [Authenticate and select a workspace](/getting-started/authenticate-and-select-workspace)
- [Environments and contexts](/guides/deploy/environments-and-contexts)