> 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: Troubleshooting
category: CLI
description: Diagnose installation, authentication, and deployment problems with the AGNT5 CLI
hideRightSidebar: true
---

`agnt5` is a single Go binary — there's no npm, nvm, or `node_modules` involved. Most issues fall into three buckets: installation, authentication/context, and deploy failures with a structured error code.


**Diagnostics**: `agnt5 --version`, `agnt5 auth status`, `agnt5 context`, `agnt5 deploy debug <deployment-id> --logs`
**Install methods**: Homebrew (`brew install agnt5dev/agnt5/agnt5`) or curl script (`curl -LsSf https://agnt5.com/cli.sh | bash`) — no npm/npx
**Deploy errors**: structured codes `DEPLOY_E001`–`DEPLOY_E024`, each with a category (preflight, build, push, provision, startup) and suggested fixes; run the failing command with `agnt5 deploy debug <id>` for details
**Not real**: `agnt5 doctor`, `agnt5 validate` (top-level), `agnt5 status`, `agnt5 config get/set`, `npm install -g agnt5` — none of these exist


## Command not found after install

The installer places the binary at `~/.agnt5/bin/agnt5`. If `agnt5` isn't found after installing:

```bash
echo 'export PATH="$HOME/.agnt5/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc
agnt5 --version
```

If you installed via Homebrew and still see "command not found," confirm the tap resolved correctly:

```bash
brew install agnt5dev/agnt5/agnt5
which agnt5
```

## Checking your install and identity

```bash
agnt5 --version        # confirm the binary and build
agnt5 auth status       # confirm you're logged in, and as whom
agnt5 context           # confirm which control plane you're targeting
```

If `auth status` reports an invalid or expired key, re-authenticate:

```bash
agnt5 auth login
```

If you're unexpectedly targeting the wrong environment, check your context — self-hosted (`byoc`) and AGNT5 Cloud (`managed`) use separate credentials. See [Context switching](/docs/cli/context.md).

## Outdated CLI

```bash
agnt5 version update   # or: agnt5 upgrade
```

If neither works — for example, an older binary without the self-update command — re-run the install script; it replaces the binary in place:

```bash
curl -LsSf https://agnt5.com/cli.sh | bash
```

## Deploy failures: structured error codes

`agnt5 deploy` reports failures with a stable code, the phase it happened in, and suggested next steps. The phases run in order — a failure in an earlier phase means later phases never ran:

| Phase | Codes | Typical cause |
| --- | --- | --- |
| **Preflight** | `DEPLOY_E001`–`E005`, `E023` | Control plane unreachable, not authenticated, invalid `agnt5.yaml`, workspace unavailable, connection timeout. |
| **Build** | `DEPLOY_E006`–`E008` | Image build failed, BuildKit unavailable, project type couldn't be detected. |
| **Push** | `DEPLOY_E009`–`E011` | Registry authentication failed, push failed, push timed out. |
| **Provision** | `DEPLOY_E012`–`E014`, `E021`, `E022` | Deployment or worker pool creation failed, dataplane not configured/connected. |
| **Startup** | `DEPLOY_E015`–`E020`, `E024` | Image pull failed, crash loop, out of memory, startup timeout, pod scheduling failed, dependency install failed. |

Each error prints its code, category, and 2–3 actionable suggestions inline. For deeper detail on a specific deployment:

```bash
agnt5 deploy debug <deployment-id>            # timeline, trace ID, K8s events
agnt5 deploy debug <deployment-id> --logs     # + container logs for failed pods
agnt5 deploy debug <deployment-id> --trace <trace-id>   # look up by trace instead of ID
```

<Callout type="tip">
Preflight errors (`E001`–`E005`, `E023`) are the fastest to fix and the most common — they mean the deploy never actually started. Run `agnt5 auth status` and `agnt5 context` first before digging into build or runtime logs.
</Callout>

## Local development issues

```bash
agnt5 dev status        # is a detached worker running?
agnt5 dev logs --follow # tail its output
agnt5 dev stop           # stop it and start fresh
agnt5 dev --verbose      # foreground, with RUST_LOG=debug and AGNT5_DEBUG=1
```

## Next steps

- [Deploy commands](/docs/cli/deploy.md): the full flag reference for `agnt5 deploy`.
- [Inspect & logs](/docs/cli/inspect.md): trace a specific run or tail deployment logs.
- [Auth commands](/docs/cli/auth.md): re-authenticate or check your identity.
- [Configuration](/docs/cli/configuration.md): environment variables and config file locations.