# Drive KubeMQ from the terminal (/deploy/cli)



`kmq` is KubeMQ's command-line client — a single static binary that talks to the
management API on port **`:8080`**, the same API the web dashboard uses. **`kmq` does
not run the broker.** It is a client, not a server: every command it runs is an HTTP
call against a KubeMQ instance that is already up.

<Callout type="info" title="Prerequisite: a running KubeMQ">
  You need a KubeMQ server already running and reachable before any of the steps below
  will work. If you don't have one yet, the [Quickstart](/deploy/quickstart) gets
  you there in a few minutes.
</Callout>

## Install [#install]

```sh
curl -sSfL https://raw.githubusercontent.com/kubemq-io/kmq/main/install.sh | sh
```

`install.sh` detects your OS and architecture, downloads the matching archive, and
performs a mandatory SHA-256 checksum verification before installing `kmq` into the
first writable `PATH` directory.

To pin a specific version instead of the latest release:

```sh
curl -sSfL https://raw.githubusercontent.com/kubemq-io/kmq/main/install.sh | sh -s -- --version v0.3.1
```

Prefer a container image over a local binary:

```sh
podman run --rm europe-docker.pkg.dev/kubemq/images/kmq:latest version
```

(`docker run` works identically in place of `podman run`.)

Full installer flags and environment variables (`KMQ_VERSION`, `KMQ_INSTALL_DIR`,
signature verification) are in the [kmq CLI reference](/operate/kmq-cli#installation).

## Connect [#connect]

`kmq` reads a **context** — a named connection profile — to know which server to talk
to. Create one pointing at your running server:

```sh
kmq context create default --api-address http://localhost:8080
```

Confirm the connection:

```sh
kmq status
```

You should see a compact JSON health digest with `is_healthy: true` — visible proof
that `kmq` can reach your KubeMQ server.

## Send your first message [#send-your-first-message]

Round-trip a message through the **Queues** pattern — guaranteed delivery, send now,
receive whenever you're ready:

```sh
kmq queue send orders '{"id":1}'
```

```sh
kmq queue receive orders
```

The second command returns the message you just sent. For a wider view across every
pattern:

```sh
kmq overview
```

## Teach your coding agent [#teach-your-coding-agent]

`kmq` ships an installable agent skill so a coding agent can drive it correctly without
guessing at flags. Three ways to install it:

```sh
npx skills add kubemq-io/kmq
```

The universal installer reaches 70+ agents — Claude Code, Cursor, Codex, Gemini CLI,
Windsurf, and more.

```sh
claude plugin marketplace add kubemq-io/kmq
```

The Claude Code plugin path, if you're already using Claude Code's plugin marketplace.

```sh
kmq skills install
```

A zero-Node fallback that installs the skill stub locally for Claude Code; add
`--global` to install it for the current user instead of just the current project.

## Where next [#where-next]

`kmq` also ships migration commands (`kmq assess kafka`, `kmq migrate
assess|replicate|translate|cutover`) that move an external Kafka cluster onto KubeMQ in
phases — see the full reference for the complete workflow.

<Cards>
  <Card title="Full kmq CLI reference" href="/operate/kmq-cli" description="Every command, flag, exit code, context, and the agent-skill distribution model." />

  <Card title="KubeMQ Aiway" href="/aiway" description="The A2A and MCP agent fabric that kmq's agent/mcp commands observe, and the skill teaches your coding agent to drive." />
</Cards>