Introduction

STU, S3 Terminal UI, is a interactive terminal-based explorer for Amazon S3 (AWS S3).

With STU, you can browse buckets and objects directly from your terminal, preview files, and download them with ease.

Key Features

• Recursive object downloads
• Previews with syntax highlighting for text files and inline rendering for images
• Access to previous object versions
• Customizable key bindings
• Support for S3-compatible storage

Built with Rust and ratatui.
STU is available on GitHub under the MIT license.

Getting Started

• Installation
• Basic Usage
• Command Line Options

Installation

Cargo

cargo install --locked stu

Homebrew

brew install stu

or from tap:

brew install lusingander/tap/stu

AUR

paru -S stu

Binary

You can download binaries from GitHub Releases.

Build from source

If you want to check the latest development version, build from source:

git clone https://github.com/lusingander/stu.git
cd stu
cargo build --release

Basic Usage

After Installation, run the following command:

stu

Basically, you can use it in the same way as the AWS CLI.

In other words, if the default profile settings exist or the environment variables are set, you do not need to specify any options.

If you want to specify it using command line options, see Command Line Options.

Command Line Options

-r, --region <REGION>

Specify the AWS region.

stu --region ap-northeast-1

-e, --endpoint-url <URL>

Specifies the AWS endpoint.

Use this if you are connecting to an S3-compatible service such as localstack, minio, or other external storage services.

stu --endpoint-url http://localhost:4566

-p, --profile <NAME>

Specifies the AWS profile name.

stu --profile foo

-b, --bucket <NAME>

Specify the bucket name.

This will not open the bucket list, but will open the object list directly. This is useful if you are only interested in or have permissions to a specific bucket.

stu --bucket bar-bucket

-P, --prefix <PREFIX>

Specifies an object prefix.

This will open only objects under the specified prefix. This option must be specified together with the --bucket option.

stu --bucket bar-bucket --prefix path/to/object/

--path-style <TYPE>

Specifies the address model for accessing S3-compatible services.

Possible values: auto, always, never

• never uses Virtual-Hosted Style, which is what AWS currently uses.
  • https://bucket.s3.region.amazonaws.com/key
• always uses Path Style, which is used when using localstack, minio, etc.
  • https://s3.region.amazonaws.com/bucket/key
• auto automatically determines which model to use, which is the default setting.

For other S3-compatible services, which one to use depends on the service.

stu --path-style auto

--debug

Enable debug logging.

Currently, the debug log only includes application-level events and logs from the AWS SDK.

-h, --help

Displays a help message.

-V, --version

Displays the version.

Configurations

You can use config.toml to configure various aspects of your application.

Config is loaded from $STU_ROOT_DIR/config.toml.

• If STU_ROOT_DIR environment variable is not set, ~/.stu is used by default.
  • If the STU_ROOT_DIR directory does not exist, it will be created automatically.
• If the config file does not exist, the default values will be used for all items.
• If the config file exists but some items are not set, the default values will be used for those unset items.

STU_ROOT_DIR

$STU_ROOT_DIR will be structured as follows:

$STU_ROOT_DIR
│
├── config.toml
│
├── keybindings.toml
│
├── error.log
│
├── debug.log
│
├── preview_theme/
│   ├── material-theme-dark.tmTheme
│   └── ...
│
└── preview_syntax/
    ├── toml.sublime-syntax
    └── ...

• Config File Format
• Syntax Highlighting

Config File Format

Example

download_dir = "$STU_ROOT_DIR/download"

max_concurrent_requests = 5

default_region = "us-east-1"

[ui.object_list]
date_format = "%Y-%m-%d %H:%M:%S"
date_width = 19

[ui.object_detail]
date_format = "%Y-%m-%d %H:%M:%S"

[ui.help]
max_help_width = 100

[preview]
highlight = false
highlight_theme = "base16-ocean.dark"

image = false

encodings = [
  "utf-8",
  "utf-16be",
  "utf-16le",
]
auto_detect_encoding = false

Configuration Options

download_dir

The directory to save the downloaded objects.

• type: string
• default: $STU_ROOT_DIR/download

$STU_ROOT_DIR will be the actual expanded value.

max_concurrent_requests

The maximum number of concurrent requests when recursive downloading objects.

• type: usize
• default: 5

default_region

The default region to use if the region cannot be obtained from the command line options or AWS settings.

• type: string
• default: us-east-1

ui.object_list.date_format

The date format of a last modified in the object list. The format must be specified in strftime format.

• type: string
• default: %Y-%m-%d %H:%M:%S

ui.object_list.date_width

The width of a last modified in the object list. It is recommended to set this when setting date_format.

• type: u16
• default: 19

ui.object_detail.date_format

The date format of a last modified in the object detail. The format must be specified in strftime format.

• type: string
• default: %Y-%m-%d %H:%M:%S

ui.help.max_help_width

The maximum width of the keybindings display area in the help.

• type: usize
• default: 100

preview.highlight

Whether syntax highlighting is enabled in the object preview.

• type: bool
• default: false

See Syntax Highlighting for details on possible values.

preview.highlight_theme

The name of the color theme to use for syntax highlighting in the object preview.

• type: string
• default: base16-ocean.dark

See Color Themes for details on possible values.

preview.image

Whether image file preview is enabled in the object preview.

• type: bool
• default: false

preview.encodings

Array of labels for the encoding want to use. Label names should be specified from https://encoding.spec.whatwg.org/#names-and-labels.

• type: array of strings
• default: ["utf-8", "utf-16be", "utf-16le"]

preview.auto_detect_encoding

Whether to enable encoding auto detection.

• type: bool
• default: false

Syntax Highlighting

In the object preview, Syntax highlighting using syntect is available.

To enable this, set preview.highlight = true in the config file.

Color Themes

You can change the color theme by specifying the theme name in preview.highlight_theme.

By default the following themes are available:

• base16-ocean.dark
• base16-eighties.dark
• base16-mocha.dark
• base16-ocean.light
  • https://github.com/SublimeText/Spacegray
• InspiredGitHub
  • https://github.com/sethlopez/InspiredGitHub.tmtheme
• Solarized (dark)
• Solarized (light)
  • https://github.com/altercation/solarized

Also, by creating xxx.tmTheme in $STU_ROOT_DIR/preview_theme/, you can use xxx and load it.

Syntax definitions

You can add syntax definitions for file types that are not supported by default.

You can use it by creating a .sublime-syntax file in $STU_ROOT_DIR/preview_syntax/.

https://www.sublimetext.com/docs/syntax.html

Keybindings

The default basic key bindings are as follows:

Detailed operations on each view can be displayed by pressing ? key.

• Custom Keybindings

Custom Keybindings

You can set your own custom key bindings.

Custom bindings are loaded from $STU_ROOT_DIR/keybindings.toml.

The default key bindings are defined in ./assets/keybindings.toml. You can set key bindings for each screen action in the same format.

• It is possible to set multiple key bindings for one action.
• If you do not set key bindings for an action, the default key bindings will be assigned.
• You can disable an action by setting [] as the key bindings.

Features

• Bucket List
• Object List
• Object Detail
• Object Preview

Bucket List

• Show list of buckets
  • Filter items by name
  • Sort items by name
• Copy the resource name of the selected bucket to the clipboard
• Recursively download objects in the selected bucket

Object List

• Show list of objects in a hierarchy
  • Filter items by name
  • Sort items by name, last modified and size
• Copy the resource name of the selected object to the clipboard
• Download object
  • Download a single selected object
  • Recursively download objects in the selected directories

Object Detail

• Show object details
• Copy the resource name of the selected object to the clipboard
• Download object
  • Download a single selected object
• Preview object
  • Preview a single selected object
• Show object versions
  • Each of the above operations can be performed for each version

Object Preview

• Syntax highlighting
  • It must be enabled in the config
• Image preview
  • It must be enabled in the config
• Open with encoding
  • Available encodings can be specified in the config
  • Automatic encoding detection (guessing)
    • It must be enabled in the config
• Download object
  • Download a single selected object

Troubleshooting

Unable to connect to S3 or compatible service

• First, check if you can connect using the AWS CLI with the same settings.
  • Are your AWS credentials configured properly?
    • This includes checking ~/.aws/credentials, environment variables, or any credential provider chain used by the AWS CLI.
  • Are the necessary permissions set correctly?
    • This includes IAM policies, roles, and bucket policies that allow operations like s3:ListBucket or s3:GetObject.
  • If you're using an S3-compatible service:
    • Is the endpoint-url set correctly?
    • Are you using the appropriate path-style access setting?
• You may be able to find more details about the error by looking at the $STU_ROOT_DIR/error.log.

Can't preview images

• Set preview.image = true in config.toml.
• Images are displayed using Sixel, iTerm2 Inline Images Protocol, and kitty Terminal graphics protocol. This feature will not work if you are using a terminal emulator that does not support any of these protocols.