Introducing doctl: the Command Line Interface to DigitalOcean

Posted 2016-03-28 in Engineering ...
blog header

Why a CLI utility?

When DigitalOcean entered the market four years ago, our team spent an extraordinary amount of time designing a web user interface that was easy to use and inviting for developers. Simple and elegant design is something we have always strived for as a company. Over time, as the amount of functionality has increased, the ease of use has remained.

That goal goes beyond just the web interface; we've sought to build an API that is just as easy to use. When we released version 1 of our API, a few popular tools emerged. Tugboat, which allowed you to manage your DigitalOcean resources from the comfort of your command line, was a particular favorite. Late last year, we deprecated V1 and released DigitalOcean API V2. With API V2 came a plethora of improvements and an enhanced developer's portal which provides information on every API endpoint along with usage examples and guides.

As developers ourselves, we spend a lot of our time in a terminal. So we have decided to upgrade that experience as well with an official command line interface (CLI) tool entitled `doctl`. `doctl` provides an accessible interface to our API, taking full advantage of improvements introduced in API V2 and support for newer DigitalOcean features like Floating IPs. It allows us to deliver more complex features and workflows as well.

Installation and usage

`doctl` is available as a precompiled binary for Linux, Mac OS X, and Windows. You can download the release on GitHub.

Getting started with `doctl` is easy. To retrieve your DigitalOcean access token and save it locally, just run:

```[php]{`doctl auth login`}```

You can view your account settings with:

```[php]{`doctl account get`}```

As an example of what `doctl` can do, we can create a Debian 8 Droplet in NYC1 with a public SSH key installed for the root user in one line:

```[php]{`doctl compute droplet create webserver01 --region nyc1 --image debian-8-x64 --size 4gb --ssh-keys 1234 --wait`}```

`doctl` can also configure the output. By default, it will be displayed in a table. If you wanted to use the output programmatically, JSON might be a better choice. For instance, you could list all of your Droplets in NYC3 as JSON using:

```[php]{`doctl compute droplet list --region nyc3 --output json`}```

To learn about all the features available, check out the full tutorial over on our community site.

Simple and powerful

`doctl` is not only an interface to the DigitalOcean V2 API. It also simplifies more complex workflows. Previously, when using the API to snapshot a Droplet, you'd have to separately retrieve the action ID and continuously query the action endpoint to know the status of the snapshot. Now `doctl` can handle that for you. Using the `--wait` flag, it can snapshot a Droplet and block until the action completes. The same concept applies to other activities which don't complete instantaneously, like Droplet creates.

`doctl` also simplifies activities which do not have an API endpoint. If you create a Droplet and don't assign the IP address in DNS, `doctl` allows you to SSH to your Droplet by name.

```[php]{`doctl compute ssh <droplet name>`}```

By default, it assumes you are using the `root` user. If you want to SSH as a specific user, you can do that as well:

```[php]{`doctl compute ssh <user>@<droplet name>`}```

Contribute

Like much of our internal tooling, `doctl` is written in Go. It is completely open source and available on GitHub. We're excited to be able to share this with our community and look forward to collaborating on building a tool we hope you'll love. Check out the contribution guidelines, and dive into the code.

What else you would like to see from `doctl`? Let us know in the comments.