---
sidebar_position: 1
sidebar_label: Overview
---

# Overview

`amctl` is the command-line interface for Agent Manager.

```
amctl [command] [TYPE] [NAME] [flags]
```

Where:

- **command:** Operation to perform — for example `login`, `get`, `create`, `delete`, `deploy`, `list`.
- **TYPE:** Resource group the command operates on — `agent`, `project`, `context`, `skills`, `build`, `traces`.
- **NAME:** Identifier of the resource. Many commands also accept the name as a flag (e.g. `--project`) or pick it up from the [linked directory](#linked-context).
- **flags:** Optional flags. See each command page for details.

If you need help on any command, run:

```bash
amctl help
amctl <command> --help
```

## Common Commands

| Command | Purpose |
|---------|---------|
| [`amctl login`](./login.mdx) | Authenticate against an Agent Manager instance |
| [`amctl context`](./context.mdx) | Inspect or switch the active instance, organization, and linked project |
| [`amctl project`](./project.mdx) | Create, list, and delete projects |
| [`amctl agent`](./agent.mdx) | Create, build, deploy, and observe agents |
| [`amctl skills`](./skills.mdx) | Install AI assistant skills locally |
| [`amctl version`](./version.mdx) | Print the CLI version |

## Global Flags

These flags are inherited by every command:

| Flag | Description |
|------|-------------|
| `--org <name>` | Override the active organization for this invocation. |
| `--json` | Emit a JSON envelope on stdout instead of human-readable text. Errors also go to stdout in JSON mode. |
| `-h`, `--help` | Show help for the current command. |

Some command groups add their own persistent flags. For example, every subcommand under `amctl agent` accepts:

| Flag | Description |
|------|-------------|
| `--project <name>` | Project that owns the agent. Falls back to the linked project. |

## Linked Context

`amctl link` associates the current working directory with an organization, project, and (optionally) an agent. Once a directory is linked, any subsequent `amctl` invocation run from that directory — or any subdirectory — automatically uses the linked context.

```bash
amctl link --project my-project --agent my-agent
amctl agent get        # resolves project + agent from the link
amctl agent deploy     # same, no flags needed
```

Linked directories always operate in the `default` environment. To override per-command, pass `--project`, `--env`, or the positional agent name explicitly.

`amctl context show` prints the resolution that will be used from the current directory.

## Output Formats

`amctl` produces two output modes:

### Text (default)

Human-readable tables or messages, written to stdout. Progress, warnings, and confirmation prompts go to stderr.

### JSON (`--json`)

A structured envelope on stdout:

```json
{
  "status": "ok",
  "scope": { "instance": "default", "org": "acme", "project": "checkout" },
  "data": { ... }
}
```

On error:

```json
{
  "status": "error",
  "scope": { ... },
  "error": { "code": "TRANSPORT", "message": "..." }
}
```

The `scope` block carries whichever scope was relevant to the call (instance, org, project, agent, env). Error `code` values are stable — safe to switch on in scripts.

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Generic failure (server error, transport error, validation failure) |
| `2` | Flag parsing error |

The wire-stable error code is in the JSON envelope, not the exit code. Scripts that need to discriminate should parse `--json` output.

## Configuration

`amctl` stores its configuration at `~/.amctl/config.yaml`. The file is created on first login and contains:

- Configured instances (URL, name, current org, auth tokens)
- The active instance
- Per-directory project links

You normally do not edit this file by hand — use `amctl login`, `amctl context instance use`, `amctl context org use`, and `amctl link` instead.

## Scope Resolution

For each invocation, `amctl` resolves the scope it operates on in this order:

1. **Instance** — `--name` on `login`, else the active instance from `~/.amctl/config.yaml`.
2. **Organization** — `--org` flag, else the linked org, else the instance's `current_org`.
3. **Project** — `--project` flag, else the linked project, else (for project-scoped commands) an error.
4. **Agent** — positional argument, else the linked agent, else a prompt or error depending on the command.
5. **Environment** (observability commands only) — `--env` flag, else the linked environment, else `default`.

Run `amctl context show` to see how scope resolves in the current directory.
