Skip to main content

cloudsh

A Python CLI that wraps common Linux commands for both local and cloud files using cloudpathlib.

Pypi Github PythonVers Building Codacy coverage

Cloud Storage Provider dependencies:

google-cloud-storage
boto3
azure-storage-blob

Installation

pip install -U cloudsh

# Install for different cloud storage providers
pip install -U cloudsh[gcs]  # Google Cloud Storage
pip install -U cloudsh[aws]  # Amazon S3
pip install -U cloudsh[azure]  # Azure Blob Storage

# Install for all cloud storage providers
pip install -U cloudsh[all]

Usage

cloudsh provides common Linux commands that work with both local and cloud files. Currently supported commands include:

  • cat: Concatenate and print files
  • cp: Copy files and directories
  • head: Output the first part of files
  • less: Display file contents with forward and backward navigation
  • ls: List directory contents
  • mkdir: Make directories
  • more: Display file contents page by page
  • mv: Move files and directories
  • rm: Remove files and directories
  • tail: Output the last part of files
  • touch: Create empty files

And two additional commands:

  • complete: Generate shell completion scripts
  • sink: Redirect output to a file

Authentication

See: https://cloudpathlib.drivendata.org/stable/authentication/ for details on how to authenticate with cloud storage providers.

The commands works on local files as the GNU/Linux commands do

$ cloudsh ls /tmp
$ cloudsh cp /tmp/file.txt /tmp/file2.txt

The commands works on cloud files

$ cloudsh ls gs://my-bucket
$ cloudsh touch gs://my-bucket/file.txt

The commands works between local and cloud files

$ cloudsh cp /tmp/file.txt gs://my-bucket/file.txt
$ cloudsh mv gs://my-bucket/file.txt /tmp/file.txt

The sink command redirects output to a file

# It is easy to redirect output to a local file
$ echo "Hello, World!" > /tmp/hello.txt
# But it is not so easy to redirect output to a cloud file, so we use `sink`
$ echo "Hello, World!" | cloudsh sink gs://my-bucket/hello.txt
# Append to a cloud file
$ echo "Hello, World!" | cloudsh sink -a gs://my-bucket/hello.txt

Drop-in Replacement for GNU/Linux Commands

Since the commands work on local files as well, you can make aliases to use cloudsh as a drop-in replacement for the GNU/Linux commands.

alias cat='cloudsh cat'
alias cp='cloudsh cp'
alias head='cloudsh head'
alias ls='cloudsh ls'
alias mkdir='cloudsh mkdir'
alias mv='cloudsh mv'
alias rm='cloudsh rm'
alias tail='cloudsh tail'
alias touch='cloudsh touch'

What if I want to use the original GNU/Linux commands?

# alias ls='cloudsh ls'
ls -- -l  # actually executes `/usr/bin/ls -l`

Shell Completion

Generating Shell Completion Scripts

cloudsh provides shell completion support, including the subcommands, options and both local and cloud paths, for bash, zsh and fish. To enable it:

# For bash
mkdir -p ~/.local/share/bash-completion
cloudsh complete --shell bash > ~/.local/share/bash-completion/cloudsh
activate-global-python-argcomplete --user
# Restart your shell
# For zsh
# Create the completions directory
mkdir -p ~/.zsh/completions

# Generate the Zsh script
cloudsh complete --shell zsh > ~/.zsh/completions/_cloudsh

# Update ~/.zshrc
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc

# Restart your shell
# For fish
cloudsh complete --shell fish > ~/.config/fish/completions/cloudsh.fish

Because of the latency when completing cloud paths, a message 'fetching ...' will be shown when completing cloud paths. export CLOUDSH_COMPLETE_NO_FETCHING_INDICATOR=1 to disable it.

Using a caching file for the completion to avoid latency when completing cloud paths

# Only cache the paths at depth 2 in the bucket
cloudsh complete --update-cache --depth 2 gs://my-bucket

Metadata

Release files for cloudsh 0.3.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cloudsh 0.3.10
File Size Uploaded Provenance Actions
cloudsh-0.3.10.tar.gz 253.5 kB Without provenance Details for cloudsh-0.3.10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cloudsh 0.3.10
File Interpreter ABI Platform Actions
cloudsh-0.3.10-py3-none-any.whl Python 3 none any Details for cloudsh-0.3.10-py3-none-any.whl

Total release size: 296.0 kB

Release files / cloudsh-0.3.10.tar.gz

Download URL cloudsh-0.3.10.tar.gz
Size 253.5 kB
Tags Source
SHA-256 checksum
How to use checksums
c6b61d98a637332de6e92744f789854cea1d6195f06433223fb4c34e9f1bb2ab
BLAKE2b-256 checksum
How to use checksums
d23a571618dc13fb7ea9d9b749fd84e1562867fdab6bad45b95e35f84eb66a96
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / cloudsh-0.3.10-py3-none-any.whl

Download URL cloudsh-0.3.10-py3-none-any.whl
Size 42.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7727e3de54757231753fd05529d61d0d057d535864bc698998a955d039c5242e
BLAKE2b-256 checksum
How to use checksums
e3b4b18a08918590e8de7b3da1bed4aeec7cd01c6fa91c19f9c81c88d045233b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for cloudsh 0.3.10

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page