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 On k3d guide first if you have not installed one. The local install exposes the Agent Manager API at http://api.amp.localhost:8080.

Step 1: Install amctl

macOS / Linux

Install the latest release with the install script. It detects your platform, verifies the checksum, and installs the binary to /usr/local/bin (or ~/.local/bin if that is not writable):

curl -fsSL https://wso2.github.io/agent-manager/install.sh | sh

tip

Set AMCTL_VERSION to pin a specific version, and AMCTL_INSTALL_DIR to change the install location:

curl -fsSL https://wso2.github.io/agent-manager/install.sh | AMCTL_VERSION=2026.11.0 AMCTL_INSTALL_DIR="$HOME/bin" sh

Windows (x64)

Download the release archive from the Agent Manager releases page. The commands below use 2026.11.0 as an example — replace it with the latest version.

Invoke-WebRequest -Uri https://github.com/wso2/agent-manager/releases/download/amp/v2026.11.0/amctl_v2026.11.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
tar -xvzf dist/*.tar.gz -C dist
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://api.amp.localhost:8080.

amctl login --url http://api.amp.localhost:8080

amctl opens a browser window for sign-in. Sign in with the same credentials you use for the Agent Manager Console. The username is admin, and the password depends on how Agent Manager was installed:

Installation	Password
On k3d or On Your Environment	Generated at install time. Retrieve it with the command below.

kubectl get secret amp-admin-credentials -n amp-thunder -o jsonpath='{.data.password}' | base64 -d

Replace amp-thunder if you installed the identity provider into a different namespace. If someone else operates your Agent Manager instance, ask them for your credentials.

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://api.amp.localhost:8080 --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://api.amp.localhost:8080 \
  --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://api.amp.localhost:8080/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.