> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensormesh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Config And Environment

> Control how the Tensormesh CLI resolves config, env vars, and local overrides.

The CLI resolves settings in this order:

1. CLI flags
2. Environment variables
3. `~/.config/tensormesh/config.toml`
4. Built-in defaults

For the Control Plane host specifically, use `--controlplane-base`,
`TENSORMESH_CONTROL_PLANE_BASE_URL`, or top-level `controlplane_base` in
`config.toml`.

If you need an alternate local state root for scripting or side-by-side environments, set `TM_CONFIG_HOME`. That moves both `config.toml` and `auth.json` together under the directory you choose.

Within `config.toml`, inference credentials live under `[overrides]`.

Use `tm config show --sources` when you need to confirm which layer actually won for each value.

## Create A Starter Config

```sh theme={null}
tm config init
tm config show
tm config show --sources
```

To write the starter template to a custom location:

```sh theme={null}
tm config init --path ./tensormesh.toml
tm --config ./tensormesh.toml config show
```

## Canonical Config File

The standard persistent CLI setup lives in:

`~/.config/tensormesh/config.toml`

Or, when `TM_CONFIG_HOME` is set:

* config: `$TM_CONFIG_HOME/config.toml`
* auth: `$TM_CONFIG_HOME/auth.json`

The standard flow is:

```sh theme={null}
tm config init
tm auth login
```

`tm config init` creates the file with user-owned request settings plus an
`[overrides]` section for the optional inference API key.

## Config File Schema

The starter template is the real schema the CLI understands today:

```toml theme={null}
# controlplane_base = "https://api.tensormesh.ai"
timeout_seconds = 30
max_retries = 0
# ca_bundle = "~/.config/tensormesh/ca-bundle.pem"

[overrides]
# gateway_api_key = "..."
```

Top-level keys:

* `controlplane_base`: optional Control Plane base URL override for auth and other Control Plane commands
* `timeout_seconds`: default HTTP timeout for commands that use the shared request client
* `max_retries`: default retry count for idempotent requests
* `ca_bundle`: optional PEM CA bundle path for TLS verification

`[overrides]` keys:

* `gateway_api_key`: stored serverless inference API key. The name stays `gateway_api_key` for config compatibility. The SDK reads the same value as `inference_api_key`.

## Single-File Design

The CLI uses a single canonical config file. If you want to change behavior manually, edit `[overrides]` in `~/.config/tensormesh/config.toml` instead of switching between named profiles or maintaining a separate runtime file.

If you want that same single-file design in a different local root, set `TM_CONFIG_HOME` instead of introducing another profile layer.

Example:

```toml theme={null}
controlplane_base = "https://api.tensormesh.ai"
timeout_seconds = 20
max_retries = 1

[overrides]
gateway_api_key = "..."
```

Inspect the resolved config and sources:

```sh theme={null}
tm --config ./tensormesh.toml config show --sources
```

`tm doctor`, `tm infer doctor`, and `tm auth status` report local config and credential presence. Use `tm auth whoami` when you need a live Control Plane auth check.

## Interpreting `config show --sources`

Use `--sources` when debugging precedence:

```sh theme={null}
tm --output json config show --sources
```

The result contains:

* `values`: resolved config after redacting secrets such as `gateway_api_key`
* `sources`: where each value came from, such as `config:timeout_seconds` or `config:gateway_api_key`

Typical source strings:

* `built-in:config_path`: CLI default
* `TENSORMESH_CONTROL_PLANE_BASE_URL`: environment override for the Control Plane base URL
* `config:controlplane_base`: explicit top-level Control Plane host from `config.toml`
* `config:gateway_api_key`: explicit user override from `[overrides]` in `config.toml`

`tm config show` and `tm config show --sources` redact secrets such as
`gateway_api_key` in both text and JSON output. That is intentional.

## Environment Variables

| Variable                            | Overrides flag        | Description                                                                                                  |
| ----------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `TENSORMESH_CONTROL_PLANE_BASE_URL` | `--controlplane-base` | Override the Control Plane base URL for CLI auth and Control Plane requests.                                 |
| `TENSORMESH_CA_BUNDLE`              | `--ca-bundle`         | Path to a PEM CA bundle for TLS verification.                                                                |
| `TENSORMESH_TIMEOUT_SECONDS`        | `--timeout`           | Default HTTP timeout in seconds.                                                                             |
| `TENSORMESH_MAX_RETRIES`            | `--max-retries`       | Max retries for idempotent requests on transient errors.                                                     |
| `TM_CONFIG_HOME`                    | —                     | Override the config and auth root directory. Moves both `config.toml` and `auth.json` to `$TM_CONFIG_HOME/`. |

`gateway_api_key` does not have an environment variable equivalent in the CLI. Set it in `[overrides]` in `config.toml`.

If you need an environment-variable-only credential workflow without a config file, use the [Tensormesh SDK](/sdk/guides/auth-and-config) instead, which supports `TENSORMESH_INFERENCE_API_KEY` and related credential variables.

## Related Reference

* [`tm`](/cli/reference)
* [`tm config`](/cli/reference/config)
* [`tm config init`](/cli/reference/config/init)
* [`tm config show`](/cli/reference/config/show)
* [`tm auth status`](/cli/reference/auth/status)
* [`tm doctor`](/cli/reference/doctor)