# 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:

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

## Common Commands[​](#common-commands "Direct link to Common Commands")

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

## Global Flags[​](#global-flags "Direct link to 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[​](#linked-context "Direct link to 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.

```
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[​](#output-formats "Direct link to Output Formats")

`amctl` produces two output modes:

### Text (default)[​](#text-default "Direct link to Text (default)")

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

### JSON (`--json`)[​](#json---json "Direct link to json---json")

A structured envelope on stdout:

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

On error:

```
{
  "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[​](#exit-codes "Direct link to 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[​](#configuration "Direct link to 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[​](#scope-resolution "Direct link to 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.