CLI Installation

amctl is the command-line interface for Agent Manager. Use it to manage organizations, projects, agents, runtime observability, and AI assistant skills from your terminal.

This guide installs amctl, logs into a running Agent Manager instance, and verifies the setup.

Prerequisites

You need a reachable Agent Manager instance before logging in. Follow the Quick Start or On k3d guide first if you have not installed one. The local install exposes the Agent Manager API at http://localhost:9000.

Step 1: Install amctl

Download the release archive for your platform from the Agent Manager releases page, extract the binary, and move it onto your PATH.

The latest published build is amctl/v0.1.0 (pre-release). Replace 0.1.0 in the commands below with a newer version once one is published.

Pre-release

amctl is currently shipped as a pre-release. Expect breaking changes between versions until the first stable release.

macOS (Apple Silicon)

curl -LO https://github.com/wso2/agent-manager/releases/download/amctl/v0.1.0/amctl_v0.1.0_darwin_arm64.tar.gz
tar -xzf amctl_v0.1.0_darwin_arm64.tar.gz
sudo mv amctl /usr/local/bin/

macOS (Intel)

curl -LO https://github.com/wso2/agent-manager/releases/download/amctl/v0.1.0/amctl_v0.1.0_darwin_amd64.tar.gz
tar -xzf amctl_v0.1.0_darwin_amd64.tar.gz
sudo mv amctl /usr/local/bin/

Linux (x64)

curl -LO https://github.com/wso2/agent-manager/releases/download/amctl/v0.1.0/amctl_v0.1.0_linux_amd64.tar.gz
tar -xzf amctl_v0.1.0_linux_amd64.tar.gz
sudo mv amctl /usr/local/bin/

Linux (ARM64)

curl -LO https://github.com/wso2/agent-manager/releases/download/amctl/v0.1.0/amctl_v0.1.0_linux_arm64.tar.gz
tar -xzf amctl_v0.1.0_linux_arm64.tar.gz
sudo mv amctl /usr/local/bin/

Windows (x64)

Invoke-WebRequest -Uri https://github.com/wso2/agent-manager/releases/download/amctl/v0.1.0/amctl_v0.1.0_windows_amd64.zip -OutFile amctl.zip
Expand-Archive amctl.zip -DestinationPath $env:USERPROFILE\amctl
$env:Path += ";$env:USERPROFILE\amctl"

To make the PATH change permanent on Windows, add %USERPROFILE%\amctl through System Properties → Environment Variables.

Build from source

If a release archive is not available for your platform, build from source:

git clone https://github.com/wso2/agent-manager.git
cd agent-manager
make amctl-build
sudo mv dist/amctl /usr/local/bin/

Verify the binary

amctl version

Step 2: Log in to Agent Manager

Run amctl login with the URL of your Agent Manager API. For a local install this is http://localhost:9000.

amctl login --url http://localhost:9000

amctl opens a browser window for sign-in. Enter the default Agent Manager credentials:

Field	Value
Username	admin
Password	admin

Once authentication completes, the CLI prints a success message and stores the session in ~/.amctl/config.yaml.

Naming the instance

Use --name if you log into more than one Agent Manager (for example a local cluster and a shared dev cluster). The name distinguishes the saved instance.

amctl login --url http://localhost:9000 --name local

Non-interactive login

For CI or scripts, use the OAuth client-credentials grant by passing both --client-id and --client-secret:

amctl login \
  --url http://localhost:9000 \
  --client-id <client-id> \
  --client-secret <client-secret>

Step 3: Verify the Setup

Confirm the CLI can reach Agent Manager and your session is active.

amctl project list

The first call after login auto-selects your organization if only one is available. If the call returns a project list (it may be empty on a fresh install), the CLI is configured correctly.

You can also list any agents you have access to:

amctl agent list

Next Steps

• Run an agent end-to-end: see Observe Your First Agent.
• Browse the command reference: start at the CLI overview for syntax and conventions.
• Install AI assistant skills: run amctl skills install to add the bundled manage-agent skill to Claude Code, Cursor, or Windsurf — see amctl skills.
• Inspect a running agent from the CLI: see amctl agent logs, metrics, and traces.

Troubleshooting

connection refused on amctl login

The Agent Manager API is not reachable at the URL you passed. For a k3d-based install, check that the port-forward or ingress is up:

curl http://localhost:9000/api/v1/healthz

Browser does not open

If amctl cannot open a browser (for example over SSH), it prints the login URL to the terminal. Copy it into a browser on your local machine, complete the login, and the CLI resumes once the callback completes.

Re-authenticating

Re-run amctl login --url <url> to refresh credentials. If you switch to a different Agent Manager instance, amctl clears any project links that pointed at the old instance and prompts you to re-link.