Create, destroy, inspect, and log on to your droplets from the command line
Perl
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib/App
t
.gitignore
.travis.yml
Changes
LICENSE
Makefile.PL
README.md
cpanfile

README.md

App::Droplets

Create, destroy, inspect, and log on to your droplets from the command line

Build Status

ABOUT

This is a command-line tool for DigitalOcean's REST API called droplets. After setting up an API key on the DigitalOcean website, you can check on all your existing droplets, query the available droplet sizes and prices by region, create new droplets, or log on to droplets (either existing droplets or ones you just created) without leaving the command line. You can also destroy one or all your droplets in one command.

INSTALLATION

The following command will install the droplets application (note that this requires git):

curl -sL cpanmin.us | perl - https://github.com/sestaton/digitalocean-cli.git

Alternatively, download the latest release and run the following command in the top directory:

perl Makefile.PL

If any Perl dependencies are listed after running this command, install them through the CPAN shell or any method you like. Then build and install the package.

perl Makefile.PL
make 
make test
make install

USAGE

The first time you run the tool you will be prompted for your API key (there is a link to a guide for setting up this token provided above in the ABOUT section of this document), so have that ready. Note that you also need to have your ssh keys set up with DigitalOcean. A configuration file (called ".droplets") will be stored in your home directory so you will not be prompted again. Once your key is stored, you are ready to go!

Examples:

Let's see get some basic information.

$ droplets --available sizes
Name	Disk_space	Memory	CPUs	Cost_per_month	Cost_per_hour	Regions
512mb	20	512	1	5	0.00744	nyc1,sgp1,ams1,sfo1,nyc2,lon1,nyc3,ams3,ams2,fra1
1gb	30	1024	1	10	0.01488	nyc2,sgp1,ams1,sfo1,lon1,nyc3,ams3,nyc1,ams2,fra1
2gb	40	2048	2	20	0.02976	nyc2,sfo1,ams1,sgp1,lon1,nyc3,ams3,nyc1,ams2,fra1
4gb	60	4096	2	40	0.05952	nyc2,ams1,sgp1,lon1,nyc3,ams3,nyc1,ams2,sfo1,fra1
8gb	80	8192	4	80	0.11905	nyc2,sgp1,ams1,nyc1,lon1,nyc3,ams3,ams2,sfo1,fra1
16gb	160	16384	8	160	0.2381	sgp1,nyc1,nyc3,lon1,nyc2,ams1,ams3,ams2,sfo1,fra1
32gb	320	32768	12	320	0.47619	nyc2,sgp1,nyc1,lon1,ams3,nyc3,ams2,sfo1,fra1
48gb	480	49152	16	480	0.71429	sgp1,nyc1,lon1,nyc2,ams3,nyc3,ams2,sfo1,fra1
64gb	640	65536	20	640	0.95238	sgp1,nyc1,nyc2,lon1,ams3,nyc3,ams2,sfo1,fra1

In the above output we can see the options available in different regions, along with the prices. Now, find out the available images..

$ droplets --available images
Distribution	ID	Name
CoreOS	12789350	723.3.0 (beta)
CentOS	6372321	5.10 x64
CentOS	6372425	5.10 x32
Debian	6372581	6.0 x64
Debian	6372662	6.0 x32
Fedora	9640922	21 x64
FreeBSD	10144573	10.1
Ubuntu	10321756	12.04.5 x64
Ubuntu	10321777	12.04.5 x32
Debian	10322059	7.0 x64
Debian	10322378	7.0 x32
CentOS	10322623	7 x64
Fedora	12065782	22 x64
Ubuntu	12658446	15.04 x64
Ubuntu	12660649	15.04 x32
Debian	12778278	8.1 x64
Debian	12778337	8.1 x32
CoreOS	13068283	723.3.0 (stable)
Ubuntu	13089493	14.04 x64
Ubuntu	13089823	14.04 x32

Now, let's create a droplet (in this case, Fedora 22)

$ droplets --imageid 12065782 --create
---------------------------------------------------
Created Droplet:         6588509
Droplet name:            187ebaa6-42ac-11e5-bd97-de968ce03bd5
Distribution:            Fedora 22 x64
Region:                  San Francisco 1
Disk:                    20
Memory:                  512mb
CPUs:                    1
Server IP:               
Creation time (seconds): 1
---------------------------------------------------

You can give the server a name, or just let a default be chosen, as above. If you want something you can remember, then specify a server name when you create the droplet. We should be able to see this droplet running if we check...

$ droplets --running
Running Droplets: 
Droplet 187ebaa6-42ac-11e5-bd97-de968ce03bd5 has id 6588509, IP address 198.199.102.123, Gateway 198.199.102.1, and Netmask 255.255.255.0

You can log on to an existing server from the command line, or create one and log on. Here, we just use the defaults...

$ droplets --create --login
Droplet name:            908c31cf-42af-11e5-8d52-9bf6c9a52cfe
Distribution:            CentOS 7 x64
Region:                  San Francisco 1
Disk:                    20
Memory:                  512mb
CPUs:                    1
Server IP:               104.236.151.89
Creation time (seconds): 1
---------------------------------------------------
[root@908c31cf-42af-11e5-8d52-9bf6c9a52cfe ~]# ls
[root@908c31cf-42af-11e5-8d52-9bf6c9a52cfe ~]# exit
logout
Connection to 104.236.151.89 closed.

You will notice the default is to log on as the root user. For images you plan to keep around, it is probably best to create regular user accounts using whatever methods apply for the Linux OS you created. Then, you can log on to the image using that user account instead of root:

$ droplets --user evan --password somesecurepass --serverid 6588509 --logon
[evan@908c31cf-42af-11e5-8d52-9bf6c9a52cfe ~]$

One final note about logging on to your droplets: you can use --login, --logon or -l to achieve the same purpose. I find this easier to work with than trying to remember the name of the command or having to look it up each time.

We can destroy a single droplet...

$ droplets --destroy --serverid 6588509
====> Before destroy...
Running Droplets:
Droplet 187ebaa6-42ac-11e5-bd97-de968ce03bd5 has id 6588509, IP address 198.199.102.123, Gateway 198.199.102.1, and Netmask 255.255.255.0
====> After destroy...
No running droplets.

Or, destroy all running droplets in one go. This convenient when you have a bunch of images that are no longer needed.

$ droplets --destroyall
====> Before destroy...
Running Droplets: 
Droplet 908c31cf-42af-11e5-8d52-9bf6c9a52cfe has id 6588977, IP address 104.236.151.89, Gateway 104.236.128.1, and Netmask 255.255.192.0
====> After destroy...
No running droplets.    

SUPPORT AND DOCUMENTATION

After installation, you can find documentation for App::Droplets with the perldoc command.

perldoc droplets

The documentation can also be accessed by specifying the manual option with droplets -m or droplets --man. The droplets program will also print a diagnostic help message when executed with no arguments. NB: I mostly used long versions of options in the examples for clarity, but typing droplets will show the short versions of the options.

ISSUES

Report any issues or feature requests at the issue tracker.

ATTRIBUTION

This project uses the Webservice::DigitalOcean library to access the DigitalOcean APIv2.

TODO

  • Add the option to change the defaults and store them in the configuration.

LICENSE

The MIT License should included with the project. If not, it can be found at: http://opensource.org/licenses/mit-license.php

Copyright (C) 2015-2017 S. Evan Staton