> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Context commands (advanced)
description: Reference for switching the CLI between AGNT5 Cloud and a self-hosted (BYOC) cluster.
category: CLI
last_verified: 2026-07-24
hideRightSidebar: true
---

**`agnt5 context`** switches which control plane the CLI talks to: **AGNT5 Cloud** (`managed`) or a **self-hosted cluster** (`byoc`). It's hidden from `--help` — these are developer/operator commands, not part of the everyday workflow — but fully invokable directly.

<Callout type="info">
`agnt5 context` is for **self-hosted / Bring Your Own Cluster (BYOC)** setups. If you use AGNT5 Cloud, you don't need it — the CLI already targets AGNT5 Cloud by default.
</Callout>


**Commands**: `agnt5 context` (show current), `agnt5 context set <managed|byoc>`, `agnt5 context list`
**Valid contexts**: `managed` (AGNT5 Cloud, default), `byoc` (Bring Your Own Cluster / self-hosted)
**Context store**: `~/.agnt5/context.yaml` (written by `context set`)
**Hidden from `--help`**: yes, but invokable directly


## Command summary

| Command | Purpose |
| --- | --- |
| `context` | Show the active context and its endpoint URLs. |
| `context list` | List available contexts, marking the active one. |
| `context set <name>` | Switch to `managed` or `byoc`. |

## `agnt5 context`

```bash
agnt5 context
```

Prints the active context (`managed` when none is stored), the API URL, the control-plane URL, and the worker-coordinator URL currently in effect.

## `agnt5 context list`

```bash
agnt5 context list
```

Lists the two available contexts and marks the active one with `*`.

## `agnt5 context set`

```bash
agnt5 context set <managed|byoc>
```

Sets the active context and writes it to `~/.agnt5/context.yaml`. The only valid values are `managed` and `byoc` — anything else errors.

- **`managed`**: Targets AGNT5 Cloud. Endpoint URLs are hardcoded defaults and are **not** persisted to disk; only the context name and `agnt5_env=agnt5-production` are written.
- **`byoc`**: Targets a self-hosted cluster. Persists every endpoint URL to `~/.agnt5/context.yaml` so you can edit them afterward: API, gateway (HTTP), gateway (gRPC), execution engine, worker coordinator, UI, NATS, auth, and OTel endpoints all default to `localhost` addresses matching the local dev stack.

Switching contexts also copies `~/.agnt5/config.<context>.yaml` over `config.yaml` when that file exists, so environment-specific credentials switch along with the context.

```bash
agnt5 context set byoc
agnt5 context set managed
```

## Configuration files

| File | Purpose |
| --- | --- |
| `~/.agnt5/context.yaml` | Active context and, for `byoc`, every endpoint URL. |
| `~/.agnt5/config.yaml` | Main credentials file, updated when contexts switch. |
| `~/.agnt5/config.managed.yaml` | Credentials specific to the `managed` context, if present. |
| `~/.agnt5/config.byoc.yaml` | Credentials specific to the `byoc` context, if present. |

<Callout type="tip">
Keep environment-specific credentials in `config.managed.yaml`/`config.byoc.yaml`. Switching contexts copies the matching file over `config.yaml`, so your API keys stay in sync with whichever cluster you just selected.
</Callout>

## Typical workflow

```bash
# 1. Check the current context
agnt5 context

# 2. Point the CLI at a local/self-hosted cluster
agnt5 context set byoc
agnt5 auth login

# 3. Work against the self-hosted stack
agnt5 projects

# 4. Switch back to AGNT5 Cloud
agnt5 context set managed
```

<Callout type="warning">
Always confirm your context before authenticating or deploying — `agnt5 context` shows which control plane you're about to talk to.
</Callout>

## Next steps

- [Auth commands](/docs/cli/auth.md): log in again after switching context — credentials are context-scoped.
- [Configuration](/docs/cli/configuration.md): the full picture of what lives under `~/.agnt5/`.
- [Local development](/docs/cli/dev.md): run the local stack that `byoc` targets by default.