cueitup lets you inspect messages in an AWS SQS queue in a simple and deliberate manner. It was built to simplify the process of investigating the contents of messages being pushed to an SNS topic. You can pull one or more messages on demand, peruse through them in a list, and, if needed, persist them to your local filesystem.

tui

web interface

Install

homebrew:

brew install dhth/tap/cueitup

go:

go install github.com/dhth/cueitup@latest

Or get the binaries directly from a release. Read more about verifying the authenticity of released artifacts here.

🛠️ Configuration

Create a YAML configuration file that looks like the following. The location of this file depends on your operating system, and can be determined by running cueitup -h.

profiles:
    # a name for a profile; you refer to it when running cueitup
  - name: profile-a #

    # the SQS queue URL
    queue_url: https://sqs.eu-central-1.amazonaws.com/000000000000/queue-a

    # use this to leverage a profile contained in the shared AWS config and credentials files
    # https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html
    aws_config_source: profile:local-profile

    # the format of the message body; possible values: [json, none]
    format: json

  - name: profile-b
    queue_url: https://sqs.eu-central-1.amazonaws.com/000000000000/queue-b
    aws_config_source: env
    format: none

  - name: profile-c
    queue_url: https://sqs.eu-central-1.amazonaws.com/000000000000/queue-c
    aws_config_source: env
    format: json

    # to only show the contents of a nested object
    subset_key: Message

    # cueitup will display this key value pair as "context" in its list
    context_key: aggregateId

⚡️ Usage

cueitup can display messages via two interfaces: a TUI or a webpage

$ cueitup tui --help

open cueitup's TUI

Usage:
  cueitup tui <PROFILE> [flags]

Flags:
  -c, --config-path string   location of cueitup's config file (default "/Users/user/Library/Application Support/cueitup/cueitup.yml")
  -d, --debug                whether to only display config picked up by cueitup
  -D, --delete-messages      whether to start the TUI with the setting "delete messages" ON (default true)
  -h, --help                 help for tui
  -P, --persist-messages     whether to start the TUI with the setting "persist messages" ON
  -M, --show-message-count   whether to start the TUI with the setting "show message count" ON (default true)
  -S, --skip-messages        whether to start the TUI with the setting "skip messages" ON

tui

$ cueitup serve --help

open cueitup's web interface

Usage:
  cueitup serve <PROFILE> [flags]

Flags:
  -c, --config-path string   location of cueitup's config file (default "/Users/user/Library/Application Support/cueitup/cueitup.yml")
  -d, --debug                whether to only display config picked up by cueitup
  -D, --delete-messages      whether to start the web interface with the setting "delete messages" ON (default true)
  -h, --help                 help for serve
  -o, --open                 whether to open web interface in browser automatically
  -S, --select-on-hover      whether to start the web interface with the setting "select on hover" ON
  -M, --show-message-count   whether to start the web interface with the setting "show message count" ON (default true)

web

Various ways to display JSON messages

Say the messages in your SQS queue look like this.

{
  "browserInfo": {
    "browserName": "Firefox",
    "browserVersion": 118,
    "deviceType": "Desktop",
    "platform": "Linux"
  },
  "isBot": true,
  "metadata": "{\"aggregateId\":\"00000000-0000-0000-0000-000000012363\",\"sequenceNr\":347}",
  "sessionId": "987e6543-b21a-34c5-d678-123456789abc",
  "transactionId": "123e4567-e89b-12d3-a456-426614174000"
}

You can configure cueitup to show a specific key value pair as “context” in its UI. You do do via the context_key configuration property.

- name: sample-profile
  queue_url: ...
  aws_config_source: ...
  format: json
  context_key: transactionId

If you want to only see the nested object under browserInfo, you’d configure a profile like this:

- name: sample-profile
  queue_url: ...
  aws_config_source: ...
  format: json
  subset_key: browserInfo
  context_key: platform

cueitup can also work with stringified JSON.

- name: sample-profile
  queue_url: ...
  aws_config_source: ...
  format: json
  subset_key: metadata
  context_key: aggregateId

TUI Keyboard shortcuts

General

Keymap	Description
`<tab>`	Switch focus to next section
`<s-tab>`	Switch focus to previous section
`?`	Show help view
`q`	Go back or quit

Message List Pane

Keymap	Description
`h/<Up>`	Move cursor up
`k/<Down>`	Move cursor down
`n`	Fetch the next message from the queue
`N`	Fetch up to 10 more messages from the queue
`}`	Fetch up to 100 more messages from the queue
`d`	Toggle deletion mode; cueitup will delete messages after reading them
`M`	Toggle polling for message count in queue
`p`	Toggle persist mode (messages will be saved to a specific location)
`s`	Toggle skipping mode (consume messages without populating the internal list)

Message Value Pane

Keymap	Description
`[`, `h`	Show details for the previous entry in the list
`]`, `l`	Show details for the next entry in the list

🔐 Verifying release artifacts

In case you get the cueitup binary directly from a release, you may want to verify its authenticity. Checksums are applied to all released artifacts, and the resulting checksum file is signed using cosign.

Steps to verify (replace A.B.C in the commands listed below with the version you want):

Download the following files from the release:
- cueitup_A.B.C_checksums.txt
- cueitup_A.B.C_checksums.txt.pem
- cueitup_A.B.C_checksums.txt.sig

Verify the signature:

cosign verify-blob cueitup_A.B.C_checksums.txt \
    --certificate cueitup_A.B.C_checksums.txt.pem \
    --signature cueitup_A.B.C_checksums.txt.sig \
    --certificate-identity-regexp 'https://github\.com/dhth/cueitup/\.github/workflows/.+' \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

Download the compressed archive you want, and validate its checksum:

curl -sSLO https://github.com/dhth/cueitup/releases/download/vA.B.C/cueitup_A.B.C_linux_amd64.tar.gz
sha256sum --ignore-missing -c cueitup_A.B.C_checksums.txt

If checksum validation goes through, uncompress the archive:

tar -xzf cueitup_A.B.C_linux_amd64.tar.gz
./cueitup
# profit!

Acknowledgements

cueitup is built using the TUI framework bubbletea.

Changelog

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

v1.0.0 - Apr 16, 2025

Added

Add support for profiles
Add web interface
Allow multiple sources for AWS config

Changed

Show error (if any) in message details pane
Change path for persisting messages

Removed

Ability to filter for messages with a specific context value