Home

Awesome

STU

Crate Status

S3 Terminal UI

About

STU is the TUI explorer application for Amazon S3 (AWS S3) written in Rust using ratatui.

<img src="./img/demo.gif">

Installation

Cargo

$ cargo install --locked stu

Homebrew (macOS)

$ brew install lusingander/tap/stu

AUR (Arch Linux)

$ paru -S stu

Binary

You can download binaries from releases.

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.

Options

STU - S3 Terminal UI

Usage: stu [OPTIONS]

Options:
  -r, --region <REGION>     AWS region
  -e, --endpoint-url <URL>  AWS endpoint url
  -p, --profile <NAME>      AWS profile name
  -b, --bucket <NAME>       Target bucket name
      --path-style <TYPE>   Path style type for object paths [default: auto] [possible values: auto, always, never]
      --debug               Enable debug logs
  -h, --help                Print help
  -V, --version             Print version

Here are some examples of how to run with options:

# Connect by specifying the profile
$ stu --profile foo-profile

# Show only the specified bucket objects
$ stu --bucket bar-bucket

# Connect to localstack, minio, etc.
$ stu --endpoint-url http://localhost:12345

# Connect by specifying environment variables
$ AWS_ACCESS_KEY_ID=abc AWS_SECRET_ACCESS_KEY=xyz stu

--path-style <TYPE>

Select the address model for S3 objects.

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

Keybindings

The basic key bindings are as follows:

KeyDescription
<kbd>Ctrl-C</kbd>Quit app
<kbd>Esc</kbd>Quit app / Close dialog
<kbd>Enter</kbd>Confirm / Open selected item
<kbd>Backspace</kbd>Go back to previous / Close dialog
<kbd>j/k</kbd>Select item / Scroll
<kbd>?</kbd>Show help

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

Config

Config is loaded from $STU_ROOT_DIR/config.toml.

Config file format

The values set in this example are the default values.

# The directory to save the downloaded objects.
# type: string
download_dir = "$STU_ROOT_DIR/download"
# The default region to use if the region cannot be obtained from the command line options or AWS settings.
# type: string
default_region = "us-east-1"

[ui.object_list]
# The date format of a last modified in the object list.
# The format must be specified in strftime format.
# https://docs.rs/chrono/latest/chrono/format/strftime/index.html
# type: string
date_format = "%Y-%m-%d %H:%M:%S"
# The width of a last modified in the object list.
# It is recommended to set this when setting date_format.
# type: u16
date_width = 19

[ui.object_detail]
# The date format of a last modified in the object detail.
# The format must be specified in strftime format.
# https://docs.rs/chrono/latest/chrono/format/strftime/index.html
# type: string
date_format = "%Y-%m-%d %H:%M:%S"

[preview]
# Whether syntax highlighting is enabled in the object preview.
# type: bool
highlight = false
# The name of the color theme to use for syntax highlighting in the object preview.
# type: string
highlight_theme = "base16-ocean.dark"
# Whether image file preview is enabled in the object preview.
# type: bool
image = 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:

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

Features / Screenshots

Bucket list

<img src="./img/bucket-list.png" width=400> <img src="./img/bucket-list-filter.png" width=400> <img src="./img/bucket-list-sort.png" width=400> <img src="./img/bucket-list-copy.png" width=400>

Object list

<img src="./img/object-list-simple.png" width=400> <img src="./img/object-list-hierarchy.png" width=400> <img src="./img/object-list-many.png" width=400> <img src="./img/object-list-filter.png" width=400> <img src="./img/object-list-sort.png" width=400> <img src="./img/object-list-dir-copy.png" width=400> <img src="./img/object-list-file-copy.png" width=400>

Object detail

<img src="./img/object-detail.png" width=400> <img src="./img/object-version.png" width=400> <img src="./img/object-download.png" width=400> <img src="./img/object-details-copy.png" width=400>

Object preview

<img src="./img/object-preview.png" width=400> <img src="./img/object-preview-image.png" width=400>

Troubleshooting

Contributing

To get started with contributing, please review CONTRIBUTING.md.

Contributions that do not follow these guidelines may not be accepted.

License

MIT