Sidebar navigationMain contentFooter
HomeServerlessMessaging and QueuingAPI/CLI
Using the NATS CLI
Jump toUpdate content

Using the NATS CLI

Reviewed on 08 June 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 Queuing 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:

Installing the NATS CLI

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

Define a context

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.

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

ActionCommand
Show a specific section of cheatsnats cheat pub
List available sectionsnats cheat --sections

Messaging

ActionCommand
Publish message from STDINecho "hello world" | nats pub destination.subject
Publish 100 messages with a random body of 100 - 1000 charactersnats 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.newnats sub ORDERS.new
Subscribe to messages, on subject source.subjectnats sub source.subject

Queuing/Streaming

ActionCommand
Adding a streamnats stream add
Viewing a streamnats stream info STREAMNAME
Removing a streamnats stream rm STREAMNAME
Show a list of streamsnats stream list
Get message 12345 in stream ORDERSnats stream get ORDERS 12345
Delete message 12345 in stream ORDERSnats stream rmm ORDERS 12345
Purge messages from stream ORDERSnats stream purge ORDERS
Mark a stream ORDERS as read onlynats stream seal ORDERS
Add a consumernats consumer add
View a consumer NEW of stream ORDERSnats consumer info ORDERS NEW
Remove consumer NEW from stream ORDERSnats consumer rm ORDERS NEW
Get messages from consumer NEW of stream ORDERSnats consumer next ORDERS NEW --ack --count=10 , nats consumer next ORDERS NEW --no-ack, nats consumer sub ORDERS NEW --ack