Using the NATS CLI

Reviewed on 09 April 2024 • Published on 20 January 2023

The NATS CLI (nats) is the official NATS tool for managing your NATS resources. It allows you to simply create and manage your streams, consumers and more.

Check out the official NATS CLI documentation for installation instructions, examples and more.

Tip

You can also configure Messaging and Queuing with the Terraform NATS Jetstream provider using our dedicated tutorial.

This page shows you how to get started with some basic actions via the NATS CLI.

Before you start

To complete the actions presented below, you must have:

A Scaleway account logged into the console
Owner status or IAM permissions allowing you to perform actions in the intended Organization
A NATS account
NATS credentials downloaded to your machine

Installing the NATS CLI

Follow instructions from the official NATS documentation. The installation process may differ depending on your OS.

To simplify your interactions with NATS hosted on Scaleway Messaging and Queuing, we recommend that you use contexts. A context is a named configuration that stores the settings (such as credentials, URLs and certificates) required to connect to NATS. By creating a context, you won’t need to specify your server and credentials with each new request.

Create a context

The example below creates a context named scaleway.

Replace {Scaleway NATS URL} with the URL of your NATS account (find this in the console on your NATS account Overview tab).
Replace {path to your creds file} with the path to the location where you downloaded your .creds file.

nats context save scaleway --server={Scaleway NATS URL} --creds={path to your creds file}

Use the saved context

Enter the following command to select the scaleway context for use:

nats context select scaleway

Create a stream

To create a stream, use the command nats stream add and follow the CLI guidelines.

Important

Bear in mind that:

Scaleway Messaging and Queuing does not support in-memory streams: choose File as storage backend.
Some system limits may apply by default.
If you choose a Retention Policy other than Work Queue you will be billed for the messages stored and retained.
Choosing three replicas has an impact on:
- The stream storage limit (as data is replicated 3 times)
- The volume of billed messages

You can connect to your stream using code, devtools or the NATS CLI (for testing purposes only).

NATS cheat sheet

Use the nats cheat command to get a list of all possible commands.

Below we provide a summary of some useful commands.

General

Action	Command
Show a specific section of cheats	`nats cheat pub`
List available sections	`nats cheat --sections`

Messaging

Action	Command
Publish message from STDIN	`echo "hello world" \| nats pub destination.subject`
Publish 100 messages with a random body of 100 - 1000 characters	nats cheat --sections``nats pub destination.subject "{{ Random 100 1000 }}" -H Count:{{ Count }} --count 100
Publish message from STDINReceive new messages received with the subject ORDERS.new	`nats sub ORDERS.new`
Subscribe to messages, on subject source.subject	`nats sub source.subject`

Queuing/Streaming

Action	Command
Adding a stream	`nats stream add`
Viewing a stream	`nats stream info STREAMNAME`
Removing a stream	`nats stream rm STREAMNAME`
Show a list of streams	`nats stream list`
Get message `12345` in stream `ORDERS`	`nats stream get ORDERS 12345`
Delete message `12345` in stream `ORDERS`	`nats stream rmm ORDERS 12345`
Purge messages from stream `ORDERS`	`nats stream purge ORDERS`
Mark a stream `ORDERS` as read only	`nats stream seal ORDERS`
Add a consumer	`nats consumer add`
View a consumer `NEW` of stream `ORDERS`	`nats consumer info ORDERS NEW`
Remove consumer `NEW` from stream `ORDERS`	`nats consumer rm ORDERS NEW`
Get messages from consumer `NEW` of stream `ORDERS`	`nats consumer next ORDERS NEW --ack --count=10` , `nats consumer next ORDERS NEW --no-ack`, `nats consumer sub ORDERS NEW --ack`