cli

README

simplemq-cli

A CLI tool for SAKURA Cloud SimpleMQ service.

Installation

Homebrew

brew install fujiwara/tap/simplemq-cli

Binary releases

https://github.com/fujiwara/simplemq-cli/releases

Usage

Usage: simplemq-cli <command> [flags]

Flags:
  -h, --help       Show context-sensitive help.
  -v, --version    Show version and exit.
      --debug      Enable debug mode ($SIMPLEMQ_DEBUG).
      --timeout    Timeout for API requests (e.g. 30s, 1m) ($SIMPLEMQ_TIMEOUT).

Commands:
  message send --queue=STRING --api-key=STRING <content> [flags]
    Send message to queue

  message receive --queue=STRING --api-key=STRING [flags]
    Receive message from queue

  message delete --queue=STRING --api-key=STRING <message-id> [flags]
    Delete message from queue

  queue create --queue=STRING [flags]
    Create a new queue

  queue list [flags]
    List queues

  queue get --queue=STRING [flags]
    Get queue details

  queue modify --queue=STRING [flags]
    Modify queue settings

  queue delete --queue=STRING [flags]
    Delete a queue

  queue message-count --queue=STRING [flags]
    Get message count in a queue

  queue rotate-api-key --queue=STRING [flags]
    Rotate API key for a queue

  queue purge --queue=STRING [flags]
    Purge all messages in a queue

Send a message

# Send a message with content argument
simplemq-cli message send --queue myqueue --api-key <api-key> "Hello, World!"

# Send a message from stdin
echo "Hello, World!" | simplemq-cli message send --queue myqueue --api-key <api-key> --stdin

# Send each line from stdin as a separate message
printf "msg1\nmsg2\nmsg3" | simplemq-cli message send --queue myqueue --api-key <api-key> --stdin --each-line

# Send each JSON value from stdin as a separate message
echo '{"a":1} {"b":2}' | simplemq-cli message send --queue myqueue --api-key <api-key> --stdin --each-json

# Send a message from a file
simplemq-cli message send --queue myqueue --api-key <api-key> --file message.txt

# Send each line from a file as a separate message
simplemq-cli message send --queue myqueue --api-key <api-key> --file messages.txt --each-line

# Send each JSON value from a file as a separate message
simplemq-cli message send --queue myqueue --api-key <api-key> --file data.json --each-json

Receive messages

# Receive a single message
# Do not delete the message after receiving
simplemq-cli message receive --queue myqueue --api-key <api-key>

# Receive with polling (wait for messages)
simplemq-cli message receive --queue myqueue --api-key <api-key> --polling --count 10

# Auto-delete messages after receiving
simplemq-cli message receive --queue myqueue --api-key <api-key> --auto-delete

Delete a message

simplemq-cli message delete --queue myqueue --api-key <api-key> <message-id>

Message Format

Note: SimpleMQ API only accepts message content matching ^[0-9a-zA-Z+/=]*$. By default, this CLI automatically encodes/decodes message content using Base64. Use --raw flag to disable this behavior.

Received messages are output as JSON to stdout.

For example:

{
  "id": "019adef1-91d4-7aac-ad68-2e1a5c881e95",
  "content": "こんにちは世界",
  "created_at": "2025-12-02T21:02:44.82+09:00",
  "updated_at": "2025-12-02T21:02:47.11+09:00",
  "expires_at": "2025-12-06T21:02:44.82+09:00",
  "acquired_at": "2025-12-02T21:02:47.11+09:00",
  "visibility_timeout_at": "2025-12-02T21:03:17.11+09:00"
}

If --raw flag is specified, the raw message from SimpleMQ API is output without Base64 decoding and time conversion.

{"id":"019adf15-f115-7efd-942c-423a6b6a2250","content":"44GT44KT44Gr44Gh44Gv5LiW55WM","created_at":1764679348501,"updated_at":1764679355018,"expires_at":1765024948501,"acquired_at":1764679355018,"visibility_timeout_at":1764679385018}

Queue Management

Queue management commands require SAKURA_ACCESS_TOKEN and SAKURA_ACCESS_TOKEN_SECRET environment variables for authentication.

Create a queue

simplemq-cli queue create --queue myqueue --description "My queue description"

List queues

simplemq-cli queue list

Get queue details

simplemq-cli queue get --queue myqueue

# Or specify queue ID directly (skips list API call for name resolution)
simplemq-cli queue get --queue-id 123456789012

Modify queue settings

# Modify visibility timeout and message expiration time
simplemq-cli queue modify --queue myqueue --visibility-timeout-seconds 60 --expire-seconds 86400

Delete a queue

# Delete with confirmation prompt
simplemq-cli queue delete --queue myqueue

# Delete without confirmation
simplemq-cli queue delete --queue myqueue -f

Get message count

simplemq-cli queue message-count --queue myqueue

Rotate API key

simplemq-cli queue rotate-api-key --queue myqueue

Purge all messages

# Purge with confirmation prompt
simplemq-cli queue purge --queue myqueue

# Purge without confirmation
simplemq-cli queue purge --queue myqueue -f

Options

Message Options

Option	Environment Variable	Description
--queue	SIMPLEMQ_QUEUE_NAME	Queue name (required)
--api-key	SIMPLEMQ_API_KEY	API Key (required)
	SAKURA_ENDPOINTS_SIMPLE_MQ_MESSAGE	Message API endpoint URL (provided by saclient-go)
--raw	SIMPLEMQ_RAW	Handle raw message without Base64 encoding/decoding (default: false)

Send Options

Option	Default	Description
--stdin	false	Read message content from stdin
--file		Read message content from a file
--each-line	false	Send each line as a separate message (requires --stdin or --file)
--each-json	false	Send each JSON value as a separate message (requires --stdin or --file)

Receive Options

Option	Environment Variable	Default	Description
--polling	SIMPLEMQ_POLLING	false	Enable polling to receive messages
--count	SIMPLEMQ_RECEIVE_COUNT	1	Number of messages to receive
--auto-delete	SIMPLEMQ_AUTO_DELETE	false	Automatically delete messages after receiving
--interval	SIMPLEMQ_POLLING_INTERVAL	1s	Polling interval

Queue Options

Queue commands require the following environment variables for authentication:

Environment Variable	Description
SAKURA_ACCESS_TOKEN	Access token for queue management (required)
SAKURA_ACCESS_TOKEN_SECRET	Access token secret for queue management (required)

Option	Environment Variable	Description
--queue, -q	SIMPLEMQ_QUEUE_NAME	Queue name (either --queue or --queue-id is required)
--queue-id	SIMPLEMQ_QUEUE_ID	Queue ID. If specified, skip name resolution via list API

Queue Create Options

Option	Description
--description	Description of the queue

Queue Modify Options

Option	Description
--visibility-timeout-seconds	Visibility timeout in seconds
--expire-seconds	Message expiration time in seconds

Queue Delete / Purge Options

Option	Environment Variable	Default	Description
-f, --force	SIMPLEMQ_FORCE	false	Force operation without confirmation prompt

API Request Rate Limit

The underlying SAKURA Cloud API client (saclient-go) enforces a rate limit of 5 requests per second by default (200ms interval between requests). This applies to all API calls including send, receive, and delete operations.

For production use with the real SimpleMQ service, the default rate limit of 5 req/s is recommended to avoid 429 Too Many Requests errors.

When using a local mock server for development, you can increase this limit for faster throughput:

export SAKURACLOUD_RATE_LIMIT=100  # 100 requests per second (10ms interval)

Local Server for Development and Testing

For local development and testing, use sakumock-simplemq, a SimpleMQ-compatible mock server. Install and run it, then point simplemq-cli at it via SAKURA_ENDPOINTS_SIMPLE_MQ_MESSAGE:

go install github.com/sacloud/sakumock/simplemq/cmd/sakumock-simplemq@latest
sakumock-simplemq

export SAKURA_ENDPOINTS_SIMPLE_MQ_MESSAGE=http://localhost:18080
export SIMPLEMQ_API_KEY=dummy  # any non-empty value is accepted by default

simplemq-cli message send --queue myqueue "Hello from sakumock!"
simplemq-cli message receive --queue myqueue

See the sakumock-simplemq README for available options (custom listen address, API key validation, SQLite-backed persistence, artificial latency, debug logging, etc.).

License

MIT

Author

fujiwara

Documentation

Index

• Variables
• func Run(ctx context.Context) error
• func UnixToTime(msec int64) time.Time
• type CLI
• type ConfirmationCommandBase
• type CreateQueueCommand
• type DeleteMessageCommand
• type DeleteQueueCommand
• type ErrNotFound
  • func (e ErrNotFound) Error() string
• type GetQueueCommand
• type ListQueueCommand
• type Message
• type MessageCommand
• type MessageCountCommand
• type ModifyQueueCommand
• type PurgeQueueCommand
• type QueueCommand
• type QueueCommandBase
  • func (b *QueueCommandBase) Validate() error
• type ReceiveMessageCommand
• type RotateAPIKeyCommand
• type SendMessageCommand
  • func (cmd *SendMessageCommand) Validate() error

Variables

var Version = "v0.9.3"

Functions

func Run

func Run(ctx context.Context) error

func UnixToTime

func UnixToTime(msec int64) time.Time

Types

type CLI

type CLI struct {
	Version kong.VersionFlag `short:"v" help:"Show version and exit."`
	Debug   bool             `help:"Enable debug mode." env:"SIMPLEMQ_DEBUG" default:"false"`
	Timeout time.Duration    `help:"Timeout for API requests (e.g. 30s, 1m)." env:"SIMPLEMQ_TIMEOUT"`

	Message *MessageCommand `cmd:"" help:"Message related commands"`
	Queue   *QueueCommand   `cmd:"" help:"Queue related commands"`
	// contains filtered or unexported fields
}

type ConfirmationCommandBase

type ConfirmationCommandBase struct {
	Force bool `help:"Force operation without confirmation prompt" short:"f" default:"false" env:"SIMPLEMQ_FORCE"`
}

type CreateQueueCommand

type CreateQueueCommand struct {
	QueueCommandBase
	Description string `help:"Description of the queue"`
}

type DeleteMessageCommand

type DeleteMessageCommand struct {
	MessageID string `arg:"" help:"ID of the message to delete" name:"message-id"`
}

type DeleteQueueCommand

type DeleteQueueCommand struct {
	QueueCommandBase
	ConfirmationCommandBase
}

type ErrNotFound

type ErrNotFound struct {
	Message string
}

func (ErrNotFound) Error

func (e ErrNotFound) Error() string

type GetQueueCommand

type GetQueueCommand struct {
	QueueCommandBase
}

type ListQueueCommand

type ListQueueCommand struct{}

type Message

type Message struct {
	ID                  string    `json:"id"`
	Content             string    `json:"content"`
	CreatedAt           time.Time `json:"created_at"`
	UpdatedAt           time.Time `json:"updated_at"`
	ExpiresAt           time.Time `json:"expires_at"`
	AcquiredAt          time.Time `json:"acquired_at"`
	VisibilityTimeoutAt time.Time `json:"visibility_timeout_at"`
}

type MessageCommand

type MessageCommand struct {
	QueueName string `name:"queue" help:"Queue name" short:"q" required:"" env:"SIMPLEMQ_QUEUE_NAME"`

	APIKey        string `help:"API Key" required:"" env:"SIMPLEMQ_API_KEY"`
	MessageAPIURL string `help:"Message API URL (deprecated: use SAKURA_ENDPOINTS_SIMPLE_MQ_MESSAGE instead)" env:"SIMPLEMQ_MESSAGE_API_URL"`
	Raw           bool   `help:"Handle raw message without Base64 encoding/decoding" default:"false" env:"SIMPLEMQ_RAW"`

	Send    *SendMessageCommand    `cmd:"" help:"Send message to queue"`
	Receive *ReceiveMessageCommand `cmd:"" help:"Receive message from queue"`
	Delete  *DeleteMessageCommand  `cmd:"" help:"Delete message from queue"`
}

type MessageCountCommand

type MessageCountCommand struct {
	QueueCommandBase
}

type ModifyQueueCommand

type ModifyQueueCommand struct {
	QueueCommandBase
	VisibilityTimeoutSeconds *int64 `help:"Visibility timeout in seconds"`
	ExpireSeconds            *int64 `help:"Message expire time in seconds"`
}

type PurgeQueueCommand

type PurgeQueueCommand struct {
	QueueCommandBase
	ConfirmationCommandBase
}

type QueueCommand

type QueueCommand struct {
	Create       *CreateQueueCommand  `cmd:"" help:"Create a new queue"`
	List         *ListQueueCommand    `cmd:"" help:"List queues"`
	Get          *GetQueueCommand     `cmd:"" help:"Get queue details"`
	Modify       *ModifyQueueCommand  `cmd:"" help:"Modify queue settings"`
	Delete       *DeleteQueueCommand  `cmd:"" help:"Delete a queue"`
	MessageCount *MessageCountCommand `cmd:"" help:"Get message count in a queue"`
	RotateAPIKey *RotateAPIKeyCommand `cmd:"" help:"Rotate API key for a queue"`
	Purge        *PurgeQueueCommand   `cmd:"" help:"Purge all messages in a queue"`
}

type QueueCommandBase

type QueueCommandBase struct {
	QueueName string `name:"queue" help:"Queue name" short:"q" env:"SIMPLEMQ_QUEUE_NAME"`
	QueueID   string `name:"queue-id" help:"Queue ID (skip name resolution if specified)" env:"SIMPLEMQ_QUEUE_ID"`
}

func (*QueueCommandBase) Validate

func (b *QueueCommandBase) Validate() error

type ReceiveMessageCommand

type ReceiveMessageCommand struct {
	Polling    bool          `help:"Enable polling to receive message" default:"false" env:"SIMPLEMQ_POLLING"`
	Count      int           `help:"Number of messages to receive" default:"1" env:"SIMPLEMQ_RECEIVE_COUNT"`
	AutoDelete bool          `help:"Automatically delete messages after receiving" default:"false" env:"SIMPLEMQ_AUTO_DELETE"`
	Interval   time.Duration `help:"Polling interval for receiving message" default:"1s" env:"SIMPLEMQ_POLLING_INTERVAL"`
}

type RotateAPIKeyCommand

type RotateAPIKeyCommand struct {
	QueueCommandBase
	ConfirmationCommandBase
}

type SendMessageCommand

type SendMessageCommand struct {
	Content  string `arg:"" optional:"" help:"Content of the message to send. if - read from stdin" name:"content"`
	Stdin    bool   `help:"Read message content from stdin" xor:"input"`
	File     string `help:"Read message content from a file" name:"file" type:"existingfile" xor:"input"`
	EachLine bool   `help:"Send each line as a separate message (requires --stdin or --file)" default:"false" name:"each-line"`
	EachJSON bool   `help:"Send each JSON value as a separate message (requires --stdin or --file)" default:"false" name:"each-json"`
}

func (*SendMessageCommand) Validate

func (cmd *SendMessageCommand) Validate() error