A fast, keyboard-driven Terminal User Interface (TUI) for exploring and managing Google Cloud Storage (GCS).
Tired of clicking through the slow Cloud Console? Want to navigate your buckets like you navigate your local file system? lazygcs brings the speed and efficiency of tools like ranger and yazi straight to your GCS workflow using an intuitive Miller Column layout.
- Miller Column Navigation: Instantly see your buckets (grouped by project), the current directory's contents, and a preview of the selected file all at once.
- Project & Bucket Insights: Get detailed information for every resource. View project IDs, names, and labels, as well as bucket locations, storage classes, and versioning status. Expand and collapse project headers to navigate multiple GCP projects seamlessly.
- Lightning Fast: Keyboard-centric workflow means your hands never have to leave the home row.
- Rich File Previews: Instantly peek at file contents and metadata. Supports styled Markdown rendering and even lets you peek inside archives (ZIP, TAR, JAR) without downloading them! For ZIPs,
lazygcsreads only the central directory, listing files instantly even for multi-GB archives. - Inline Search: Instantly filter your buckets or objects. Supports exact matching or configurable fuzzy search.
- Multi-Select & Batch Downloads: Select multiple files or entire directories and download them all concurrently. Directories are automatically packaged into
.ziparchives! - Easy Resource Management: Create new buckets, directories, or empty files directly from the TUI with a single keypress (
n), or delete existing items with a confirmation prompt (x). - Object Versions Support: Toggle the view of all previous versions for any object with a single keypress (
v). - Vim-like Keybindings:
j/kfor vertical movement,h/lfor entering and exiting directories,Ctrl+u/Ctrl+dfor page scrolling. - Cross-Platform: Works seamlessly on macOS, Linux, and Windows.
brew tap idan-at/tap
brew install lazygcscurl -1sLf 'https://dl.cloudsmith.io/public/idan-at/lazygcs/setup.deb.sh' | sudo -E bash
sudo apt install lazygcscurl -1sLf 'https://dl.cloudsmith.io/public/idan-at/lazygcs/setup.rpm.sh' | sudo -E bash
sudo dnf install lazygcscurl -1sLf 'https://dl.cloudsmith.io/public/idan-at/lazygcs/setup.alpine.sh' | sudo -E bash
sudo apk add lazygcsYou can download the pre-compiled binaries (including .deb, .rpm, and .apk packages) directly from the Releases page.
For example, to install the .deb package on Debian/Ubuntu:
wget https://github.com/idan-at/lazygcs/releases/download/v0.10.1/lazygcs_0.10.1_linux_amd64.deb
sudo apt install ./lazygcs_0.10.1_linux_amd64.debEnsure you have Go (v1.24+) installed, then run:
go install github.com/idan-at/lazygcs@latestAlternatively, clone the repository and build it manually with optimization flags (to reduce binary size):
git clone https://github.com/idan-at/lazygcs.git
cd lazygcs
go build -ldflags="-s -w" -o lazygcs main.go
sudo mv lazygcs /usr/local/bin/Run lazygcs to start the application.
You can initialize a configuration file with the init command:
lazygcs init --project p1 --project p2You can use the --version flag to print the current version:
lazygcs --versionlazygcs is configured entirely via a TOML file.
The easiest way to generate a config file is using the init command:
lazygcs init --project my-production-project --project my-staging-projectAlternatively, you can manually create a file at ~/.config/lazygcs/config.toml (or define the LAZYGCS_CONFIG environment variable to point to a custom path).
# Required: A list of Google Cloud Project IDs you want to explore.
projects = ["my-production-project", "my-staging-project"]
# Optional: The directory where files will be downloaded.
# Defaults to ~/Downloads if not specified.
download_dir = "/Users/me/Desktop/gcs_downloads"
# Optional: Enable fuzzy searching when using the '/' filter.
# Defaults to true. To use exact substring matching, set this to false.
fuzzy_search = false
# Optional: Replace the default standard emojis with Nerd Font icons.
# Requires a Nerd Font to be installed and active in your terminal.
# Defaults to false (standard emojis are used).
nerd_icons = truelazygcs relies on the standard Google Cloud Go SDK authentication. Make sure you are authenticated with your Google Cloud account before running the tool:
gcloud auth application-default loginRequired IAM Permissions:
To use lazygcs, the authenticated user or service account must have at least the following roles:
roles/storage.objectViewer(to list and read objects)roles/storage.buckets.list(if you need to list buckets across a project)
j/kor↓/↑: Move cursor down/uplorEnteror→: Enter a bucket or directoryhor←: Go back to the parent directory or bucket list
space: Toggle selection of the highlighted item (Multi-select)n: Create a new bucket, directory, or empty filex: Delete the currently highlighted item (requires confirmation)d: Download the currently highlighted item (or all selected items)/: Start filtering the current columnqorCtrl+c: Quit the application.
For a complete and detailed list of all keybindings, please see docs/KEYBINDINGS.md.
Contributions, issues, and feature requests are welcome! Feel free to check the issues page.