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.
• flags: Optional flags. See each command page for details.

If you need help on any command, run:

amctl help
amctl <command> --help

Common Commands

Command	Purpose
amctl login	Authenticate against an Agent Manager instance
amctl context	Inspect or switch the active instance, organization, and linked project
amctl project	Create, list, and delete projects
amctl agent	Create, build, deploy, and observe agents
amctl skills	Install AI assistant skills locally
amctl version	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.

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:

{
  "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

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.