Skip to main content
Copy page
Version: Cloud

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 an Agent Manager Cloud account before logging in. Sign up at console.agent-manager.cloud.wso2.com.

Step 1: Install amctl​

Pre-release

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

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=0.0.0-dev AMCTL_INSTALL_DIR="$HOME/bin" sh

Windows (x64)​

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

Invoke-WebRequest -Uri https://github.com/wso2/agent-manager/releases/download/amp/v0.0.0-dev/amctl_v0.0.0-dev_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 cloud API.

amctl login --url https://console.agent-manager.cloud.wso2.com

amctl opens a browser window for sign-in. Enter the default Agent Manager 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 deployment and a shared cloud deployment). The name distinguishes the saved instance.

amctl login --url https://console.agent-manager.cloud.wso2.com --name cloud

Non-interactive login​

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

amctl login \
  --urlhttps://console.agent-manager.cloud.wso2.com \
  --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: run amctl help, or amctl <command> --help, 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.
  • Inspect a running agent from the CLI: use amctl agent logs, amctl agent metrics, and amctl agent 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 https://console.agent-manager.cloud.wso2.com/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.