_____ __        _ 
   ____|__  // /___  __(_)
  / ___//_  / __/ / / / / 
 (__  )__/ / /_/ /_/ / /  
/____/____/\__/\__,_/_/

s3tui - S3 Compatible Transfer CLI

s3tui is a powerful terminal-based application that enables seamless file transfers between your local machine and multiple AWS S3 accounts. Crafted with the ratatui Rust TUI framework, s3tui provides a robust user interface for managing uploads and downloads simultaneously in both directions, enhancing your productivity with S3 services.

Features

• Multiple Account Support: Easily configure and switch between different S3 accounts during runtime using the 's' command.
• Simultaneous Transfers: Transfer multiple files at once, both to and from S3, thanks to multithreading capabilities powered by the tokio library.
• Sortable File Lists: Sort files by name, size, or type in both local and S3 panels using F1/F2/F3 keys.
• Search/Filter: Quickly filter files by name using / key. Search is case-insensitive and filters both panels.
• Interactive Commands:
  • Tab,↔ - move between local and s3 panel
  • s - select account currently in use.
  • Esc - move back to the file manager window.
  • ↕ / j / k - move up/down on the lists.
  • t - select/deselect files to transfer.
  • c - create bucket.
  • ⌫ / Del - delete item.
  • l - Display currently selected files for transfer.
  • r - Execute the selected transfers.
  • F1 - Sort by name (press again to toggle ascending/descending).
  • F2 - Sort by size (press again to toggle ascending/descending).
  • F3 - Sort by type (press again to toggle ascending/descending).
  • F5 - Refresh current view.
  • / - Search/filter files by name (Esc to clear filter).
  • q - Quit the application.
  • ? - Access the help page with all available commands.
• Environment Configuration: Customize settings via environment variables or utilize default settings compliant with the XDG Base Directory Specification.
• Error Handling: Integrated color_eyre panic hook for clear and colorized error reporting.
• Version Information: Quickly view the application version with the --version command.

Setup

1. Configure Environment Variables:

    export S3TUI_CONFIG=`pwd`/.config
    export S3TUI_DATA=`pwd`/.data
    export S3TUI_LOGLEVEL=info
   

   Alternatively, use the default paths set according to the XDG Base Directory Specification.

   You can check your configuration by running s3tui --version which will show you the paths currently in use.

2. Add your s3 credentials

   • Add as many configurations under creds directory (inside your .data directory specified with S3TUI_DATA env variable)
   • The file should look like the one below:

access_key=YOUR_ACCESS_KEY
secret_key=YOUR_SECRET_KEY
default_region=eu-west-1

Make sure there is a new line at the end and there are no leading spaces on the lines.

S3-Compatible Storage

s3tui supports S3-compatible storage providers. Example credential file:

access_key=minioadmin
secret_key=minioadmin
default_region=us-east-1
endpoint_url=http://127.0.0.1:9000
force_path_style=true

The force_path_style parameter controls URL formatting:

• false (default): Virtual-hosted style (bucket.endpoint/key)
• true: Path style (endpoint/bucket/key)

3. Installation from crates.io:

   • Ensure you have Rust and cargo installed.
   • Install/Upgrade with cargo

     cargo install s3tui
   

4. Building locally:

   • Ensure you have Rust and cargo installed.
   • Clone the repository and build the project:

     git clone <repository-url>
     cd s3tui
     cargo build --release
   

5. Running s3tui:

• Navigate to the project directory and run:

./target/release/s3tui

Logs

Application logs are efficiently managed and stored in the directory specified by S3TUI_DATA, keeping you informed of all operations and aiding in troubleshooting.

Getting Started

Once s3tui is running, press ? to open the help page, which displays all the commands and their functions, allowing you to start transferring files immediately.

Enhance your productivity with s3tui, the command-line interface that bridges the gap between local file management and cloud storage with ease and efficiency. Whether you're managing large datasets or performing routine backups, s3tui makes S3 file transfer tasks intuitive and manageable directly from your terminal.

Development

Building

# Debug build
cargo build

# Release build
cargo build --release

# Run directly
cargo run

Testing

# Run unit tests
cargo test

# Run property-based tests
cargo test --test property_tests

# Run all tests including integration tests (requires Docker)
cargo test -- --include-ignored

# Run only integration tests (requires Docker)
cargo test --test s3_compat_tests -- --ignored

# Run a specific test
cargo test test_name

# Run benchmarks
cargo bench

Integration tests use testcontainers to spin up MinIO containers automatically. Make sure Docker is running before executing integration tests.

Benchmarks use criterion for performance measurement.

Code Quality

# Run linter
cargo clippy

# Format code
cargo fmt

# Check formatting without changes
cargo fmt -- --check

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository and create your branch from main
2. Make your changes and ensure tests pass
3. Run the linter (cargo clippy) and fix any warnings
4. Format your code (cargo fmt)
5. Submit a pull request with a clear description of your changes

Guidelines

• Follow Rust idioms and best practices
• Add tests for new functionality
• Update documentation as needed
• Keep commits focused and atomic
• Use descriptive commit messages

Reporting Issues

Found a bug or have a feature request? Please open an issue with:

• A clear description of the problem or feature
• Steps to reproduce (for bugs)
• Your environment (OS, Rust version, s3tui version)

License

This project is licensed under the MIT License - see the LICENSE file for details.