spaces-cli

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:

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.