{"id":13598963,"url":"https://github.com/lusingander/stu","last_synced_at":"2025-04-10T03:56:00.702Z","repository":{"id":104325398,"uuid":"443060159","full_name":"lusingander/stu","owner":"lusingander","description":"TUI explorer application for Amazon S3 (AWS S3) 🪣","archived":false,"fork":false,"pushed_at":"2025-04-06T00:07:28.000Z","size":24399,"stargazers_count":527,"open_issues_count":9,"forks_count":16,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-10T03:55:56.808Z","etag":null,"topics":["amazon-s3","aws","aws-s3","ratatui","s3","s3-browser","s3-client","s3-explorer","terminal","tui"],"latest_commit_sha":null,"homepage":"https://lusingander.github.io/stu/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lusingander.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-30T11:52:19.000Z","updated_at":"2025-04-10T03:50:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"cb46436c-e86b-4d64-809d-2f239b7e7ab0","html_url":"https://github.com/lusingander/stu","commit_stats":{"total_commits":105,"total_committers":1,"mean_commits":105.0,"dds":0.0,"last_synced_commit":"64d7463dec28a1697c587d6963563809e34046fd"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lusingander%2Fstu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lusingander%2Fstu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lusingander%2Fstu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lusingander%2Fstu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lusingander","download_url":"https://codeload.github.com/lusingander/stu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248155001,"owners_count":21056542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-s3","aws","aws-s3","ratatui","s3","s3-browser","s3-client","s3-explorer","terminal","tui"],"created_at":"2024-08-01T17:00:58.543Z","updated_at":"2025-04-10T03:56:00.692Z","avatar_url":"https://github.com/lusingander.png","language":"Rust","funding_links":[],"categories":["Rust","\u003ca name=\"online\"\u003e\u003c/a\u003eOnline search and resources","💻 Apps","Table of Contents"],"sub_categories":["🚀 Productivity and Utilities"],"readme":"# STU\n\n[![Crate Status](https://img.shields.io/crates/v/stu.svg)](https://crates.io/crates/stu)\n\nS3 Terminal UI 🪣\n\n\u003cimg src=\"./img/demo.gif\"\u003e\n\n## About\n\nSTU is the TUI explorer application for Amazon S3 (AWS S3) written in Rust using [ratatui](https://github.com/ratatui/ratatui).\n\nSTU provides the following features:\n\n- Recursive download of objects\n- Preview with syntax highlighting for text and image rendering\n- Access to past versions of objects\n- Customizable key bindings\n- Support for S3-compatible storage\n\nCheck out the [Features / Screenshots](#features--screenshots) section for more details!\n\n## Installation\n\n### [Cargo](https://crates.io/crates/stu)\n\n```\n$ cargo install --locked stu\n```\n\n### [Homebrew (macOS)](https://github.com/lusingander/homebrew-tap/blob/master/stu.rb)\n\n```\n$ brew install lusingander/tap/stu\n```\n\n### [AUR (Arch Linux)](https://aur.archlinux.org/packages/stu)\n\n```\n$ paru -S stu\n```\n\n### Binary\n\nYou can download binaries from [releases](https://github.com/lusingander/stu/releases).\n\n## Usage\n\nAfter installation, run the following command:\n\n```\n$ stu\n```\n\nBasically, you can use it in [the same way as the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).\n\nIn 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.\n\n### Options\n\n```\nSTU - S3 Terminal UI\n\nUsage: stu [OPTIONS]\n\nOptions:\n  -r, --region \u003cREGION\u003e     AWS region\n  -e, --endpoint-url \u003cURL\u003e  AWS endpoint url\n  -p, --profile \u003cNAME\u003e      AWS profile name\n  -b, --bucket \u003cNAME\u003e       Target bucket name\n      --path-style \u003cTYPE\u003e   Path style type for object paths [default: auto] [possible values: auto, always, never]\n      --debug               Enable debug logs\n  -h, --help                Print help\n  -V, --version             Print version\n```\n\nHere are some examples of how to run with options:\n\n```sh\n# Connect by specifying the profile\n$ stu --profile foo-profile\n\n# Show only the specified bucket objects\n$ stu --bucket bar-bucket\n\n# Connect to localstack, minio, etc.\n$ stu --endpoint-url http://localhost:12345\n\n# Connect by specifying environment variables\n$ AWS_ACCESS_KEY_ID=abc AWS_SECRET_ACCESS_KEY=xyz stu\n```\n\n#### --path-style \\\u003cTYPE\\\u003e\n\nSelect the address model for S3 objects.\n\n- `never` uses Virtual-Hosted Style, which is what AWS currently uses.\n  - `https://bucket.s3.region.amazonaws.com/key`\n- `always` uses Path Style, which is used when using localstack, minio, etc.\n  - `https://s3.region.amazonaws.com/bucket/key`\n- `auto` automatically determines which model to use, which is the default setting.\n\nFor other S3-compatible services, which one to use depends on the service.\n\n### Keybindings\n\n#### Default\n\nThe basic key bindings are as follows:\n\n| Key                  | Description                  |\n| -------------------- | ---------------------------- |\n| \u003ckbd\u003eCtrl-C\u003c/kbd\u003e    | Quit app                     |\n| \u003ckbd\u003eEnter\u003c/kbd\u003e     | Confirm / Open selected item |\n| \u003ckbd\u003eBackspace\u003c/kbd\u003e | Go back to previous          |\n| \u003ckbd\u003ej/k\u003c/kbd\u003e       | Select item / Scroll         |\n| \u003ckbd\u003e?\u003c/kbd\u003e         | Show help                    |\n\nDetailed operations on each view can be displayed by pressing `?` key.\n\n#### Custom keybindings\n\nYou can set your own custom key bindings.\n\nCustom bindings are loaded from `$STU_ROOT_DIR/keybindings.toml`.\n\nThe default key bindings are defined in [./assets/keybindings.toml](./assets/keybindings.toml). You can set key bindings for each screen action in the same format.\n\n- It is possible to set multiple key bindings for one action.\n- If you do not set key bindings for an action, the default key bindings will be assigned.\n- You can disable an action by setting `[]` as the key bindings.\n\n### Config\n\nConfig is loaded from `$STU_ROOT_DIR/config.toml`.\n\n- If `STU_ROOT_DIR` environment variable is not set, `~/.stu` is used by default.\n  - If the `STU_ROOT_DIR` directory does not exist, it will be created automatically.\n- If the config file does not exist, the default values will be used for all items.\n- If the config file exists but some items are not set, the default values will be used for those unset items.\n\n#### Config file format\n\nThe values set in this example are the default values.\n\n```toml\n# The directory to save the downloaded objects.\n# type: string\ndownload_dir = \"$STU_ROOT_DIR/download\"\n# The maximum number of concurrent requests when recursive downloading objects.\n# type: usize\nmax_concurrent_requests = 5\n# The default region to use if the region cannot be obtained from the command line options or AWS settings.\n# type: string\ndefault_region = \"us-east-1\"\n\n[ui.object_list]\n# The date format of a last modified in the object list.\n# The format must be specified in strftime format.\n# https://docs.rs/chrono/latest/chrono/format/strftime/index.html\n# type: string\ndate_format = \"%Y-%m-%d %H:%M:%S\"\n# The width of a last modified in the object list.\n# It is recommended to set this when setting date_format.\n# type: u16\ndate_width = 19\n\n[ui.object_detail]\n# The date format of a last modified in the object detail.\n# The format must be specified in strftime format.\n# https://docs.rs/chrono/latest/chrono/format/strftime/index.html\n# type: string\ndate_format = \"%Y-%m-%d %H:%M:%S\"\n\n[ui.help]\n# The maximum width of the keybindings display area in the help.\n# type: usize\nmax_help_width = 100\n\n[preview]\n# Whether syntax highlighting is enabled in the object preview.\n# type: bool\nhighlight = false\n# The name of the color theme to use for syntax highlighting in the object preview.\n# type: string\nhighlight_theme = \"base16-ocean.dark\"\n# Whether image file preview is enabled in the object preview.\n# type: bool\nimage = false\n# Array of labels for the encoding want to use.\n# Label names should be specified from https://encoding.spec.whatwg.org/#names-and-labels.\n# type: array of strings\nencodings = [\n  \"utf-8\",\n  \"utf-16be\",\n  \"utf-16le\",\n]\n```\n\n### Syntax highlighting\n\nIn the object preview, Syntax highlighting using syntect is available. To enable this, set `preview.highlight = true` in the config file.\n\n#### Color themes\n\nYou can change the color theme by specifying the theme name in `preview.highlight_theme`.\n\nBy default the following themes are available:\n\n- `base16-ocean.dark`\n- `base16-eighties.dark`\n- `base16-mocha.dark`\n- `base16-ocean.light`\n  - https://github.com/SublimeText/Spacegray\n- `InspiredGitHub`\n  - https://github.com/sethlopez/InspiredGitHub.tmtheme\n- `Solarized (dark)`\n- `Solarized (light)`\n  - https://github.com/altercation/solarized\n\nAlso, by creating `xxx.tmTheme` in `$STU_ROOT_DIR/preview_theme/`, you can use `xxx` and load it.\n\n#### Syntax definitions\n\nYou 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/`.\n\nhttps://www.sublimetext.com/docs/syntax.html\n\n## Features / Screenshots\n\n### Bucket list\n\n- Show list of buckets\n  - filter/sort items\n- Download object\n  - Recursive download of selected buckets\n- Copy resource name to clipboard\n\n\u003cimg src=\"./img/bucket-list.png\" width=400\u003e \u003cimg src=\"./img/bucket-list-filter.png\" width=400\u003e \u003cimg src=\"./img/bucket-list-sort.png\" width=400\u003e \u003cimg src=\"./img/bucket-list-copy.png\" width=400\u003e \u003cimg src=\"./img/bucket-list-download-confirm.png\" width=400\u003e\n\n### Object list\n\n- Show list of objects in a hierarchy\n  - filter/sort items\n- Download object\n  - Recursive download of selected directories\n- Copy resource name to clipboard\n\n\u003cimg src=\"./img/object-list-simple.png\" width=400\u003e \u003cimg src=\"./img/object-list-hierarchy.png\" width=400\u003e \u003cimg src=\"./img/object-list-many.png\" width=400\u003e \u003cimg src=\"./img/object-list-filter.png\" width=400\u003e \u003cimg src=\"./img/object-list-sort.png\" width=400\u003e \u003cimg src=\"./img/object-list-dir-copy.png\" width=400\u003e \u003cimg src=\"./img/object-list-file-copy.png\" width=400\u003e \u003cimg src=\"./img/object-list-download-confirm.png\" width=400\u003e\n\n### Object detail\n\n- Show object details\n- Show object versions\n- Download object\n  - Download the specified version\n- Preview object\n  - Preview the specified version\n- Copy resource name to clipboard\n\n\u003cimg src=\"./img/object-detail.png\" width=400\u003e \u003cimg src=\"./img/object-version.png\" width=400\u003e \u003cimg src=\"./img/object-download.png\" width=400\u003e \u003cimg src=\"./img/object-details-copy.png\" width=400\u003e\n\n### Object preview\n\n- syntax highlighting (by [syntect](https://github.com/trishume/syntect))\n  - It must be enabled in the [config](#config-file-format)\n- image preview (by [ratatui-image](https://github.com/benjajaja/ratatui-image))\n  - It must be enabled in the [config](#config-file-format)\n- open with encoding\n  - Available encodings can be specified in the [config](#config-file-format)\n\n\u003cimg src=\"./img/object-preview.png\" width=400\u003e \u003cimg src=\"./img/object-preview-image.png\" width=400\u003e \u003cimg src=\"./img/object-preview-encoding.png\" width=400\u003e\n\n## Troubleshooting\n\n- If you're having trouble connecting, first verify that the AWS CLI can successfully access the same S3 resources:\n  - Are your AWS credentials configured properly?\n    - This includes checking `~/.aws/credentials`, environment variables, or any credential provider chain used by the AWS CLI.\n  - Are the necessary permissions set correctly?\n    - This includes IAM policies, roles, and bucket policies that allow operations like `s3:ListBucket` or `s3:GetObject`.\n  - If you're using an S3-compatible service:\n    - Is the `endpoint-url` set correctly?\n    - Are you using the appropriate `path-style` access setting?\n- If an error occurs, check the error log at `$STU_ROOT_DIR/error.log`.\n  - For more detailed information, run with the `--debug` flag and inspect `$STU_ROOT_DIR/debug.log`.\n    - Currently, the debug log only includes application-level events and logs from the AWS SDK.\n\n## Contributing\n\nTo get started with contributing, please review [CONTRIBUTING.md](CONTRIBUTING.md).\n\nContributions that do not follow these guidelines may not be accepted.\n\n## Related projects\n\n- [DDV](https://github.com/lusingander/ddv) - Terminal DynamoDB Viewer ⚡️\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flusingander%2Fstu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flusingander%2Fstu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flusingander%2Fstu/lists"}