> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-07-24
title: Configuration
category: CLI
description: Where the AGNT5 CLI stores credentials and settings, and how to override them with flags and environment variables
hideRightSidebar: true
---

The CLI has no `agnt5 config` command. Configuration lives in three places: a **project manifest** (`agnt5.yaml`) committed to your repo, **user config** under `~/.agnt5/` for credentials and endpoints, and **environment variables** that override both at runtime.


**Project manifest**: `agnt5.yaml` in the project root (language, deploy defaults, build config)
**User config**: `~/.agnt5/config.yaml` (credentials), `~/.agnt5/context.yaml` (endpoint context, BYOC only)
**Env vars**: `AGNT5_API_KEY`, `AGNT5_API_URL`, `AGNT5_CONTEXT`, `AGNT5_DEFAULT_WORKSPACE_ID`, plus per-service URL overrides — see table below
**Global flags**: `--env-file <path>`, `--output`/`-o` (`text`\|`json`), `--json` (deprecated alias for `--output json`)
**Precedence**: env vars > `~/.agnt5/config.yaml` / `context.yaml` > built-in defaults. CLI flags win for anything they cover directly (e.g. `--env` on `deploy`).
**Not real**: `agnt5.config.js`, `agnt5.config.json`, `agnt5 config get/set/list/reset` — none of these exist


## Project manifest: `agnt5.yaml`

Every linked project has an `agnt5.yaml` in its root, created by `agnt5 create`/`agnt5 init`. It holds the project's language and deployment defaults and is read by `agnt5 deploy`, `agnt5 build`, and `agnt5 dev`. There is no `agnt5.config.js` or `agnt5.config.json` — those don't exist.

Together with `.agnt5/project-ref` (which binds the directory to a project ID), `agnt5.yaml` is what makes a directory an "AGNT5 project." See [Project & workspace commands](/docs/cli/project.md#local-project-files) for how both files are created and used.

## User config: `~/.agnt5/`

| File | Purpose |
| --- | --- |
| `~/.agnt5/config.yaml` | Credentials — written by `agnt5 auth login`, read on every invocation. |
| `~/.agnt5/context.yaml` | Active context and, for `byoc`, endpoint URLs. Written by `agnt5 context set`. See [Context switching](/docs/cli/context.md). |
| `~/.agnt5/config.managed.yaml`, `~/.agnt5/config.byoc.yaml` | Context-specific credential overlays, if present — copied over `config.yaml` when you switch context. |

Most users never touch these files directly — `agnt5 auth login` and `agnt5 context set` manage them.

## Global flags

These apply to every `agnt5` command, not just a specific one:

| Flag | Description |
| --- | --- |
| `--env-file <path>` | Load CLI environment variables from a dotenv file instead of (or in addition to) the shell environment. |
| `--output <format>`, `-o` | `text` or `json`. Defaults to `text` on a terminal, `json` when the output is piped. |
| `--json` | Deprecated alias for `--output json`. Prefer `--output json`. |

```bash
agnt5 deploy --env-file .env.ci --output json
agnt5 inspect runs ls | jq '.[] | .id'   # --output defaults to json when piped
```

## Environment variables

Environment variables always override `~/.agnt5/config.yaml` and `context.yaml`.

| Variable | Purpose |
| --- | --- |
| `AGNT5_API_KEY` | API key. Set this to skip `agnt5 auth login` entirely — useful in CI. |
| `AGNT5_API_URL` | Control-plane API URL. |
| `AGNT5_CONTEXT` | `managed` or `byoc`. Overrides the value stored in `context.yaml`. |
| `AGNT5_DEFAULT_WORKSPACE_ID` | Default workspace, instead of prompting or using `agnt5 workspace use`. |
| `AGNT5_GATEWAY_URL` / `AGNT5_GATEWAY_GRPC_URL` | Runtime gateway HTTP/gRPC endpoints. |
| `AGNT5_WORKER_COORDINATOR_URL` / `AGNT5_COORDINATOR_ENDPOINT` | Worker coordinator endpoint. |
| `AGNT5_EE_ENDPOINT` / `AGNT5_ENGINE_URL` | Execution engine endpoint. |
| `AGNT5_UI_URL` | Studio/UI URL. |
| `AGNT5_NATS_URL` | NATS endpoint (self-hosted only). |
| `AGNT5_AUTH_URL` | OAuth provider URL used by `agnt5 auth login`. |
| `AGNT5_OTEL_ENDPOINT` | OpenTelemetry collector endpoint. |
| `AGNT5_DEBUG` | Set to `1` for verbose worker logging. Set automatically by `agnt5 dev --verbose`. |
| `RUST_LOG` | Log level for the local worker runtime, e.g. `info,agnt5=debug,sdk_core=debug`. Set automatically by `agnt5 dev --verbose`. |

<Callout type="tip">
For CI, set `AGNT5_API_KEY` (from `agnt5 service-keys create`) and skip `agnt5 auth login` — the CLI picks it up automatically. Pass a dotenv file with `--env-file` if you'd rather not export variables directly.
</Callout>

## Next steps

- [Auth commands](/docs/cli/auth.md): the command that actually writes `~/.agnt5/config.yaml`.
- [Context switching](/docs/cli/context.md): AGNT5 Cloud vs. self-hosted (BYOC) endpoints.
- [Service keys](/docs/cli/service-keys.md): mint an `AGNT5_API_KEY` for CI.
- [Project & workspace commands](/docs/cli/project.md): what `agnt5.yaml` and `.agnt5/project-ref` do.