Skip to content

☁️ Quickly upload and download files from DigitalOcean Spaces.

License

Notifications You must be signed in to change notification settings

BetaHuhn/spaces-cli

Repository files navigation

spaces-cli

GitHub David npm

Quickly upload and download files from DigitalOcean Spaces.

👋 Introduction

spaces-cli lets you quickly upload and download files from DigitalOcean Spaces. You can upload individual files or entire directories to any of your spaces associated with your DigitalOcean account. Instantly get a link to your uploaded files, or download a file simply by providing its Spaces URL.

🚀 Get started

Install spaces-cli globally via npm:

npm install -g spaces-cli

Make sure you already have a DigitalOcean Space (of not, you can create one here)

Then start the interactive setup with:

spaces-cli setup

Or specify all options via command line arguments or environment variables on each run.

Refer to the setup-options section for more details on all required and optional configuration options.

After that you are ready to upload/download your files! 🎉

📚 Usage

Usage: spaces-cli [command] [options]

Commands:
  upload|up [options] <files...>  Upload file/s or directories to DO spaces
  download|down [options] <file>  Download file from DO spaces
  config [options]                Output current config
  setup|start [options]           Start interactive setup
  help [command]                  display help for command

Options:
  -t, --upload-to <path>         path to upload file to
  -o, --output <path>            path/file name of downloaded file
  -s, --space <name>             specify the name of your DO space
  -r, --region <name>            specify the region of your space
  -a, --access <permission>      file permission public/private (default: private)
  -i, --access-key-id <key>      space access key id
  -k, --secret-access-key <key>  space secret key
  -c, --custom-domain <name>     specify custom CDN endpoint
  -d, --debug                    enable debug mode (default: false)
  -h, --help                     display help for command

Check out the examples below to help you get started.

⚙️ Setup Options

Here are all the options spaces-cli takes:

Name Description Env Variable Command Line Arg Required
Access Key ID Needs to be generated on your DO account page (here) ACCESS_KEY_ID --access-key-id Yes
Secret Access Key Needs to be generated on your DO account page (here) SECRET_ACCESS_KEY --secret-access-key Yes
Space Name Name of your Space SPACE --space Yes
Space Region Region where your Space is located REGION --region Yes
Access File permission, either public/private (default: private) ACCESS --access No
Custom Domain Use a custom domain/CDN endpoint (only used for output) CUSTOM_DOMAIN --custom-domain No
Upload To Specify a upload directory to use UPLOAD_TO --upload-to No
Output Path/file name for downloaded file N/A --output Only for download
Debug Enable debug mode to get more output on what's happening DEBUG --debug No

Note: for convenience, you can also specify the space name and region via one option like this: --space name.region or SPACE=name.region

There are multiple ways to specify these values. Each of them can either be specified via command line arguments (e.g. --access-key-id xxx), set as an environment variable (e.g. ACCESS_KEY_ID=xxx), or stored permanently in a configuraton file via the setup command (Note: Command line arguments will take precedence over environment variables and the stored configuration file).

The recommended way to use spaces-cli is to save your ACCESS_KEY_ID and SECRET_ACCESS_KEY via the setup command once and then specify all other options as command line arguments on each run.

Command Line Arguments

You can specify each value individually as an command line argument when running any command. Run spaces-cli help <command> to see which options are available for each command.

Interactive Setup Command

If you don't want to specify these values every time you run the command, you can store them permanently in a configuration file.

Start the interactive setup process with this command:

spaces-cli setup

The configuration will be stored in your home directory: ~/.config/configstore/spaces-cli.json and can be returned at any point with the config command.

Environment Variables

As mentioned above, you can also store the values as environment variables. They have to be uppercase and words need be seperated by underscores, e.g ACCESS_KEY_ID.

🛠️ Examples

All examples below assume that you have saved your ACCESS_KEY_ID and SECRET_ACCESS_KEY either via the setup command or as environment variables. All other options will be specifed as command line arguments.

Upload a file

Command:

$ spaces-cli up file.txt -s space-name -r region

Output:

✔  Uploaded to: http://space-name.region.digitaloceanspaces.com/file.txt

Specify upload path:

Command:

$ spaces-cli up file.txt -t /folder/name/file.txt -s space-name -r region

Output:

✔  Uploaded to: http://space-name.region.digitaloceanspaces.com/folder/name/file.txt

Upload multiple files

Command:

$ spaces-cli up file.txt file2.txt -t /folder/name/ -s space-name -r region

Output:

✔  Uploaded to: http://space-name.region.digitaloceanspaces.com/folder/name/file.txt
✔  Uploaded to: http://space-name.region.digitaloceanspaces.com/folder/name/file2.txt

Upload directories

Command:

$ spaces-cli up /from/folder -t /to/folder -s space-name -r region

Output:

✔  All files uploaded to:  https:/space-name.region.digitaloceanspaces.com/to/folder/

Download a file

Command:

$ spaces-cli down http://space-name.region.digitaloceanspaces.com/folder/name/file.txt

or

$ spaces-cli down /folder/name/file.txt -s space-name -r region

Output:

✔  Downloaded to: file.txt

Specify output file:

Command:

$ spaces-cli down http://space-name.region.digitaloceanspaces.com/folder/name/file.txt -o newFile.txt

Output:

✔  Downloaded to: newFile.txt

💻 Development

Issues and PRs are very welcome!

  • run yarn lint or npm run lint to run eslint.
  • run yarn build or npm run build to build a single file in the dist folder.

This project adheres to Semantic Versioning. To see differences with previous versions refer to the CHANGELOG.

❔ About

This project was developed by me (@betahuhn) in my free time. If you want to support me:

Donate via PayPal

ko-fi

Or use my referral link https://m.do.co/c/779397b07aaa to get 100$ Credit on DigitalOcean (I get 25$)

spaces-cli is in no way affiliated with DigitalOcean.

📄 License

Copyright 2021 Maximilian Schiller

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