Common CLI Behavior

Todo

Document the plain doapi command

API Authentication

In order to perform API requests, an OAuth token must be supplied to doapi so that it can authenticate with the DigitalOcean server. You can generate an OAuth token for your account via the “Apps & API” section of your DigitalOcean account’s control panel.

The doapi commands will look for an OAuth token in the following locations, in order:

  1. Specified on the command line with --api-token token or --api-token-file file
  2. The value of the DO_API_TOKEN environment variable
  3. The contents of a .doapi file in your home directory

Handling Non-Uniqueness of Identifiers

Most resources in the API are referred to by only a single identifier each, but droplets, images, and SSH keys can be referred to by either a unique ID number, a unique slug (for certain images), a unique fingerprint (for SSH keys), or a (potentially) non-unique name.

When the user specifies an object identifier that could be an ID, slug, fingerprint, or name, the default order of resolution is as follows:

  1. If the identifier is an integer and there is an object of the relevant type with that integer as its ID number, doapi uses that object.
  2. For images, if there is an image whose slug equals the identifier, doapi uses that image.
  3. For SSH keys, if the identifier is in the form of an SSH public key fingerprint (16 colon-separated two-digit hexadecimal integers) and there is an SSH key with that fingerprint registered with the user’s DigitalOcean account, doapi uses that SSH key.
  4. Otherwise, the identifier is assumed to be a name, and if there exists exactly one object of the relevant type with that name, doapi uses that object. If there is not exactly one object with that name, doapi will exit without taking any action; if the name is shared by multiple objects, the error message will include all of the objects’ ID numbers.

For subcommands that operate on lists of objects, this behavior can be changed by passing the --multiple option to the subcommand, causing any identifier shared by multiple objects of the relevant type (whether as ID, slug, fingerprint, and/or name) to be interpreted as a list of all of those objects in unspecified order.

In all cases, if the same object is specified more than once on the command line, all occurrences after the first are ignored with a warning.

Changed in version 0.2.0: --multiple now also matches by ID, slug, & fingerprint

Todo

Mention --unique and the warnings in its absence

Universal Options

All commands take the following options in addition to those listed in their individual documentation:

--api-token <token>

Use <token> as an OAuth token for authentication with the API; mutually exclusive with --api-token-file

--api-token-file <file>

Use the contents of <file> (after stripping leading & trailing whitespace) as an OAuth token for authentication with the API; mutually exclusive with --api-token

--endpoint <URL>

Use <URL> as the base URL for all API requests; default value: https://api.digitalocean.com (the official DigitalOcean API endpoint)

--help

Show command usage and exit

--timeout <seconds>

The maximum number of seconds to wait when attempting to connect to or read from the remote endpoint; default value: no timeout

--version

Show doapi version and exit

Note that these options (other than --help) cannot be attached to subcommands:

doapi-droplet --timeout 1000 show  # Good
doapi --timeout 1000 droplet show  # Good
doapi-droplet show --timeout 1000  # Bad!

Waiting Options

By default, all subcommands that perform non-atomic actions return immediately after initiating the action, without waiting for it to complete. They can be made to instead wait until completion with the --wait option, which can be configured further with --wait-interval and --wait-time, as described below:

-w, --wait

Periodically poll the server for the current status of all actions until they all complete or error out or until the time limit specified by --wait-time is exceeded. If this action is not specified, the subcommand will exit immediately after initiating the actions.

--wait-interval <seconds>

How often to poll the server for the actions’ current statuses; default value: 2 seconds

Changed in version 0.2.0: Default value changed from 5 seconds to 2 seconds

--wait-time <seconds>

The maximum number of seconds to wait for all actions to complete. After this much time has passed since program invocation, any remaining in-progress actions will be output immediately without waiting for them to finish.

If --wait is specified but this option is not, the subcommand will wait indefinitely.