Engineering

Introducing doctl: the Command Line Interface to DigitalOcean

Posted: March 28, 20163 min read

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 Reserved 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:

doctl auth login

You can view your account settings with:

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:

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:

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.

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:

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.

Share

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!Sign up

Related Articles

Dolphin: Mastering the Art of Automated Droplet Movement
engineering

Dolphin: Mastering the Art of Automated Droplet Movement

January 23, 20243 min read

DigitalOcean's journey to Python Client generation
engineering

DigitalOcean's journey to Python Client generation

January 26, 20233 min read

How DigitalOcean uses Let’s Encrypt
engineering

How DigitalOcean uses Let’s Encrypt

November 28, 20223 min read