Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lusingander/stu
TUI (Terminal/Text UI) application for AWS S3 🪣
https://github.com/lusingander/stu
amazon-s3 aws aws-s3 ratatui s3 s3-browser s3-client terminal tui
Last synced: 3 days ago
JSON representation
TUI (Terminal/Text UI) application for AWS S3 🪣
- Host: GitHub
- URL: https://github.com/lusingander/stu
- Owner: lusingander
- License: mit
- Created: 2021-12-30T11:52:19.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-04-21T08:54:50.000Z (8 months ago)
- Last Synced: 2024-04-30T07:17:33.392Z (8 months ago)
- Topics: amazon-s3, aws, aws-s3, ratatui, s3, s3-browser, s3-client, terminal, tui
- Language: Rust
- Homepage: https://lusingander.github.io/stu/
- Size: 8.01 MB
- Stars: 75
- Watchers: 3
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ratatui - stu - A TUI for AWS S3. (💻 Apps / 🚀 Productivity and Utilities)
README
# STU
[](https://crates.io/crates/stu)
S3 Terminal UI
## About
STU is the TUI explorer application for Amazon S3 (AWS S3) written in Rust using [ratatui](https://github.com/ratatui/ratatui).
## Installation
### [Cargo](https://crates.io/crates/stu)
```
$ cargo install --locked stu
```
### [Homebrew (macOS)](https://github.com/lusingander/homebrew-tap/blob/master/stu.rb)
```
$ brew install lusingander/tap/stu
```
### [AUR (Arch Linux)](https://aur.archlinux.org/packages/stu)
```
$ paru -S stu
```
### Binary
You can download binaries from [releases](https://github.com/lusingander/stu/releases).
## Usage
After installation, run the following command:
```
$ stu
```
Basically, you can use it in [the same way as the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
In other words, if the default profile settings exist or [the environment variables are set](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html), you do not need to specify any options.
### Options
```
STU - S3 Terminal UI
Usage: stu [OPTIONS]
Options:
-r, --region AWS region
-e, --endpoint-url AWS endpoint url
-p, --profile AWS profile name
-b, --bucket Target bucket name
--path-style 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:
```sh
# 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 \
Select the address model for S3 objects.
- `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.
### Keybindings
The basic key bindings are as follows:
| Key | Description |
| -------------------- | ---------------------------------- |
| Ctrl-C | Quit app |
| Esc | Quit app / Close dialog |
| Enter | Confirm / Open selected item |
| Backspace | Go back to previous / Close dialog |
| j/k | Select item / Scroll |
| ? | Show help |
Detailed operations on each view can be displayed by pressing `?` key.
### Config
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.
#### Config file format
The values set in this example are the default values.
```toml
# 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:
- `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
## Features / Screenshots
### Bucket list
- Show list of buckets
- filter/sort items
- Copy resource name to clipboard
### Object list
- Show list of objects in a hierarchy
- filter/sort items
- Copy resource name to clipboard
### Object detail
- Show object details
- Show object versions
- Download object
- Download the specified version
- Preview object
- Preview the specified version
- Copy resource name to clipboard
### Object preview
- syntax highlighting (by [syntect](https://github.com/trishume/syntect))
- It must be enabled in the [config](#config-file-format)
- image preview (by [ratatui-image](https://github.com/benjajaja/ratatui-image))
- It must be enabled in the [config](#config-file-format)
## Troubleshooting
- If you cannot connect to AWS S3, first check whether you can connect using the AWS CLI with the same settings.
- By running with the `--debug` flag, logs will be output to `$STU_ROOT_DIR/debug.log`.
- Currently, application events and AWS SDK logs are output.
- Pressing `F12` while the application is running will dump the application state to the log.
- When reporting a problem, please include the information like the following.
- Application version
- Operating system and version
- Terminal you are using
- Steps to reproduce the issue
- Relevant log files or error messages
## Contributing
To get started with contributing, please review [CONTRIBUTING.md](CONTRIBUTING.md).
Contributions that do not follow these guidelines may not be accepted.
## License
MIT