NATS CLI for coding agents

When a coding agent needs to inspect services that exchange messages, it can use the official NATS command-line tool, nats, to send commands to NATS servers and manage their resources from a shell. NATS is a messaging system that lets services exchange messages; JetStream adds stored messages and tools for managing streams and consumers. A stream is a named store for messages, and a consumer tracks which messages a client has received.

An agent can use nats to check whether a stream exists and review its settings before changing code that depends on it. The CLI can also create, publish, or delete data, so give the agent credentials that allow only the work it needs to do.

Install the CLI and configure access

The NATS CLI repository documents installation through Go, Homebrew, Scoop, Arch Linux packages, and GitHub releases. For a Go environment, install the command with:

go install github.com/nats-io/natscli/nats@latest

The agent also needs access to a NATS server. NATS checks credentials or certificates to confirm a client’s identity. Store those credentials outside the agent’s prompt, then configure a named CLI context, a saved connection profile with settings such as the server address and authentication details. The CLI stores contexts as JSON files under ~/.config/nats/context. Use nats context add --help to see the options supported by the installed CLI. A context with a server address and a credentials file can look like this:

nats context add NAME --server nats://SERVER:4222 --creds /path/to/user.creds --description "Agent read access"

Replace the upper-case placeholders and the file path with your own values. Pointing to a credentials file keeps its contents out of the command line. Avoid putting passwords or credential contents in shell commands that the agent can read or log.

After you add a context, list available contexts with nats context ls and select the one you want with nats context select NAME. The selected context directs commands to its configured server, so check it before asking an agent to inspect or manage resources. You can also pass --context NAME to a single command, which makes the target visible in the command itself.

Inspect a JetStream stream

A useful read-only task is checking whether a stream exists and reviewing its settings before changing a service that publishes to it. With the right context selected, run:

nats stream ls
nats stream info STREAM_NAME

Replace STREAM_NAME with the actual stream name. The first command lists streams visible to the configured account. The second shows information about one stream. The JetStream tutorial describes that output in two parts. The configuration part shows settings like subjects and storage, and the state part shows the message count and active consumers. These commands read data from the server; they do not create or change a stream. Both accept --json when the agent needs output it can parse. The output depends on the account and the streams present, so do not assume a particular stream name or result.

A prompt for that task could be:

Use the configured NATS context to list JetStream streams and inspect orders. Do not publish messages or change server resources. Report whether the stream exists and summarize its reported configuration.

Here orders stands for your own stream name. If the context lacks permission to inspect streams, the command will fail; ask the NATS administrator to grant the required access rather than sharing broader credentials with the agent.

Know what the command can change

The CLI also manages consumers, key-value stores, and object stores, along with other NATS resources. It can publish and subscribe to messages. A shell-enabled agent can use these commands for infrastructure work, but it can also change server state. Limit inspection tasks to read commands, and require explicit approval before the agent runs a command that adds, purges, or otherwise changes a resource. The NATS CLI README shows examples for the main command groups. Check a command’s --help output before relying on a particular option.

Core NATS delivers messages to subscribers connected when a message is published, and the server does not store those messages for later. If a subscriber is offline, it does not receive that message. JetStream stores messages and lets clients read them again for use cases that need those features. Use a stream inspection command when you need to understand stored messages; do not treat a Core NATS subscription as a history of past traffic.