Installation • Getting Started • Features • Configuration • Troubleshooting

---

Amazon Dynamo-DB Query Engine for the Terminal.
A fast 2-pane TUI full of QoL features.

🚧 WORK IN PROGRESS 🚧

Warning

This is a work in progress!

Breaking changes may occur!

🤖 AI NOTICE 🤖

Note

At least up until the first release,

this project will be exclusively hand-crafted.

❔ Why

I wanted a TUI for quickly finding and browsing Amazon Dynamo-DB items. It needed quality of life features such as the ability to toggle columns on or off, easily copying items or fields, and sorting by a given field.

I couldn't find one that felt exactly right to me, so I decided to build one myself.

📦 Installation

Install the package using go:

# install
go install github.com/wolfwfr/dynamite/cmd/dynamite@latest

# execute
dynamite

Or build it from source:

# obtain
git clone git@github.com/wolfwfr/dynamite.git
cd dynamite

# install
make install

# execute
dynamite

🔨 Getting Started

Help

For help, simply run:

dynamite --help

Execute

Install Dynamite. Then execute with the valid AWS credentials:

Note

Dynamite can only perform read-operations.

With AWS Credentials in Environment

# AWS_SESSION_TOKEN=*******
# AWS_PROFILE=******
dynamite

With an AWS Profile Flag

dynamite --aws_profile="my-profile"

TUI

• Navigate with arrow-keys or vim-bindings
• Quit with ctrl+c at any point
• Get Help with ?
• Tab between panes to shift focus for navigation or scrolling
• Select a table with Enter
• Search with /
• Escape search-mode and dialogs with Esc
• Move Back to the tables view with Backspace
• Much more: see the help menu (with ?)

✨ Features

Among others, Dynamite offers:

• Easy Authentication: AWS authentication through environment or profile
• Region Selection: select and switch AWS region within the TUI
• Fuzzy Finding: quickly search and find what you need
• Syntax Highlighting: JSON/YAML views of your items with highlighting
• Visibility Toggle: only display the columns you're interested in
• Easy Sorting: quickly sort your results by any field (S, B, N)
• Quick Copy: Copy table name, item field or the item JSON/YAML immediately
• Scan/Query: Scan and Query your table, select index, order, and set keys
• Filter: Apply DynamoDB's filter capability to narrow down your search
• Open in Browser: Swiftly open the table or item in your browser and edit
• ZOOM: Don't need the second pane? Zoom in and only display what you need
• Transform: transform unix timestamps to human readable ones

🔧 Configuration

By default, the config.yaml is stored in a dynamite-tui sub-directory at your OS default config location:

• Unix/Linux: {XDG_CONFIG_HOME} or{HOME}/.config/
• windows: {AppData}/
• darwin/ios: {HOME}/Library/Application Support/

A custom config_path can be provided to the CLI with --cfg or the DYNAMITE_TUI_CONFIG_DIR ENVIRONMENT variable.

Here is the default configuration:

# merges with built-in list of currently existing regions
aws_regions: []

# starred_regions appear at the top of the selection
starred_regions: []

# region that is selected by default
default_region: us-east-1

# enables defaulting to region used in the session that was most recently closed
default_to_last_region: false

# default AWS profile to look for when no relevant ENVIRONMENT variables were found
default_profile: ""

# settings for the table-selection-view
tables:
  # percentage of screen width occupied by primary table-selection-pane
  primary_width_percent: 50
  # limit of number of tables retrieved upon opening DYNAMITE
  max_tables: 1000
  # page-size override, paginates tables from dynamodb with given pagesize, by default page-size depends on window-size
  page_size: 0
  # list of strings that are parsed to regular-expressions, used to highlight table-names
  highlight_regexp: []

# settings for the item-selection-view
items:
  # percentage of screen width occupied by primary item-selection-pane
  primary_width_percent: 50
  # page-size override, paginates items from dynamodb table with given pagesize, by default page-size depends on window-size
  page_size: 0
  # item preview formatting, either 'json' or 'yaml', case-insensitive
  format: json

colors:
  # All theme colours can be overridden here

Overriding Theme Colours

To observe the yaml tags to use for overriding theme colours, have a look at the pkg/theme/overrides.go file.

Tip

apply the values 'nil' or 'transparent' to remove the colour. This renders foreground colours in the terminal's default colour and background colours are not rendered at all.

Example

# <config_path>/dynamite-tui/config.yaml
colors:
  terminal_default_color: "#FF0808"
  spinner_symbol_fg: nil

Highlighting Table Names

Table names can be highlighted by matching them against regular expressions that you define in the configuration file.

how it works

• Expressions that fail to compile are ignored.
• Each table name is matched against the expressions in order.
• The first full match wins.
• A matching expression MUST match the entire name.
• A matching expression MUST capture each element in the name.
• Each captured element will be uniquely highlighted.

Example

# <config_path>/dynamite-tui/config.yaml
tables:
  highlight_regexp:
    - ^(staging|prod)(.*-service)(.*)$
    - ^(staging|prod)(.*-api)(.*)$

The above configuration will match as follows:

table-name	matching expression	highlighted segments	number of segments
prod-happiness-service-YEF15	1	[prod, -happiness-service, -YEF15]	3
staging-cataclysm-service-EFI89	1	[staging, -cataclysm-service, -EFI89]	3
staging-chaos-api-YAK36	2	[staging, -chaos-service, -YAK36]	3
NewYork-rockstar-api	NONE	[NewYork-rockstar-api]	1

🛣 Roadmap

☝️ This is a work in progress and the following is required for a first release:

• Code Polish: the code and its style require some polishing
• Theme Polish: dark & light theme compatibility & tweaking of theme colours
• README Polish: expand the README with images and video among others

✌️ Other features I have in mind are:

• Keymap Configuration: use the config file to change the keymapping
• Themes: additional themes
• Merged Feature Dialog: Merging the various dialogs to streamline the experience for users that prefer fewer keybindings.

✋ Non Goals

• ADMIN Mode: Although I'm considering it, I'm currently flagging write operations as a non-goal
• Full API Compatibility: Full integration with all of the aws-sdk-go-v2 dynamo-db related functions
• Mouse Support: Support for navigating the TUI using the mouse cursor

🫴 Alternatives

• Sacha another 2-pane TUI that also integrates with S3, EC2, Lambda, and more!
• ddv a blazing fast dynamo-DB viewer for the terminal, written in Rust

🩼 Troubleshooting

Logging

Dynamite offers logging capabilities, review CLI help to see all options:

dynamite --help

Enable logs at the specified level:

# level options: [ trace debug info warn error ]
dynamite --log --level warn

Direct logs to a path of choice:

# prints logs to relative path: ./dynamite.log
dynamite --log --log_path .

Enable debug logs:

# equivalent to `dynamite --log --level debug`
dynamite --debug

FAQ

Scrolling down doesn't automatically retrieve the next page

If not all pages have been retrieved, it is possible that pagination is disabled because of an enabled search (default key: /) or because page-retrieval had been explicitly canceled by pressing the Esc key during page-retrieval (in which case a PAGING box should appear in the bottom-left corner). Re-enable pagination with the c key, or view the help menu (default key: ?) for the appropriate key-binding.

My scan or query is not returning the expected results

If filter parameters were left enabled, then they will affect your search results. Check for the FILTER box in the bottom-left corner, if it is depicted, then filters are being applied. Open the filter-parameters dialog (default key: f), reset (default key: ctrl+r), and commit (default key: alt+enter). This should remove any applied filters to your current operation. Note that Dynamite maintains a separate set of filter-parameters for scan- & query-modes and stores a session per table that restores any scan-, query-, and filter-parameters when re-selecting that table within the same Dynamite session.

I cannot enable search or sort

The search and sorting features are mutually exclusive. If you cannot use one of them, then you likely have the other enabled. They are not compatible because search implements its own sorting based on match-score.