# 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](/agent-manager/docs/next/getting-started/quick-start/.md) or [On k3d](/agent-manager/docs/next/getting-started/on-k3d/.md) guide first if you have not installed one. The local install exposes the Agent Manager API at `http://localhost:9000`.

## Step 1: Install amctl[​](#step-1-install-amctl "Direct link to Step 1: Install amctl")

Download the release archive for your platform from the [Agent Manager releases page](https://github.com/wso2/agent-manager/releases), 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)[​](#macos-apple-silicon "Direct link to 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)[​](#macos-intel "Direct link to 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)[​](#linux-x64 "Direct link to 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)[​](#linux-arm64 "Direct link to 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)[​](#windows-x64 "Direct link to 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[​](#build-from-source "Direct link to 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[​](#verify-the-binary "Direct link to Verify the binary")

```
amctl version
```

## Step 2: Log in to Agent Manager[​](#step-2-log-in-to-agent-manager "Direct link to 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[​](#non-interactive-login "Direct link to 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[​](#step-3-verify-the-setup "Direct link to 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[​](#next-steps "Direct link to Next Steps")

* **Run an agent end-to-end:** see [Observe Your First Agent](/agent-manager/docs/next/tutorials/observe-first-agent/.md).
* **Browse the command reference:** start at the [CLI overview](/agent-manager/docs/next/cli/overview/.md) 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`](/agent-manager/docs/next/cli/skills/.md).
* **Inspect a running agent from the CLI:** see [`amctl agent logs`](/agent-manager/docs/next/cli/agent/.md#amctl-agent-logs), [`metrics`](/agent-manager/docs/next/cli/agent/.md#amctl-agent-metrics), and [`traces`](/agent-manager/docs/next/cli/agent/.md#amctl-agent-traces).

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### `connection refused` on `amctl login`[​](#connection-refused-on-amctl-login "Direct link to 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[​](#browser-does-not-open "Direct link to 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-authenticating "Direct link to 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.