localsqs

A basic CLI wrapper for ElasticMQ designed for mocking SQS locally.

Table of contents

• Overview
• Installation
• Usage
  • Commands
  • Examples
• Configuration
• Error Handling
• Development
• License

Overview

localsqs is a command-line tool for interacting with ElasticMQ, which provides a local, in-memory implementation of Amazon SQS. It allows developers to test and mock SQS behavior locally without needing AWS infrastructure.

This tool uses the ElasticMQ REST API to interact with queues, send and receive messages, and manage queue attributes.

Usage

npx localsqs --help

You can use the CLI with the command npx localsqs.

Commands <required arg> [optional arg]

• up: Start ElasticMQ in Docker.

  Options:

  • --api-port (default: 9324): Port for the REST-SQS API.
  • --ui-port (default: 9325): Port for the UI.
  • --force or -f: Forcefully terminate processes occupying specified ports before starting.

• createQueue <queueName>: Create a new SQS queue.
• deleteQueue <queueName>: Delete a specified queue.
• listQueues [namePrefix]: List all queues or filter by prefix.
• purgeQueue <queueName>: Purge all messages from a specified queue.
• send <queueName> [messageBody]: Send a message to a queue. You can provide messageBody as a JSON string or pipe JSON data.

  Options:

  • --sns: Will wrap the payload in a SNS-like message format.

• receive <queueName>: Receive messages from a specified queue.
• getQueueUrl <queueName>: Get the URL for a specified queue.
• getQueueAttributes <queueName>: Retrieve attributes of a queue.

💡 Type --help after any command to see the available options.

Examples

Start ElasticMQ

npx localsqs up

With custom ports

npx localsqs up --api-port 9334 --ui-port 9335 --force

Create a queue

npx localsqs createQueue myQueue

Send a message

npx localsqs send myQueue "hello world" --sns

With piped input

cat message.json | npx localsqs send myQueue --sns

Read the messages in a queue

npx localsqs receive myQueue

List all queues

npx localsqs listQueues

Configuration

The tool defaults to connecting to ElasticMQ on http://127.0.0.1:9324 for the API and http://127.0.0.1:9325 for the UI.

💡 Use the --api option on a command to override the default API URL.

Error handling

localsqs uses fetch for API requests.

A common error is ECONNREFUSED, which may occur if ElasticMQ is not running or if there is an issue with the specified API port. Non-200 HTTP responses from ElasticMQ will also trigger errors.

Development

1. Clone the repository and install dependencies.
2. Build the project:

   npm run build

3. Link the project for CLI testing:

   npm link

4. You can now use localsqs as a command.