Home Serverless Messaging and Queuing API/CLI

Using the NATS CLI

Reviewed on 20 January 2023 • 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 Queueing with the Terraform NATS Jetstream provider - take a look at our tutorial here.

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

Security & Identity (IAM):

You may need certain IAM permissions to carry out some actions described on this page. This means:

you are the Owner of the Scaleway Organization in which the actions will be carried out, or
you are an IAM user of the Organization, with a policy granting you the necessary permission sets

Requirements:

You have an account and are logged into the Scaleway console
You have created a NATS Messaging namespace
You have generated credentials for your NATS Messaging and Queuing namespace and downloaded them 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 a NATS namespace. 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 namespace (find this in the console on your Namespaces dashboard).
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`

Queueing/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`