CLI Documentation

CLI style guide

User experience is at the core of Akamai CLI. Follow our best practices to create consistent and user-friendly custom commands.

Overview

Akamai CLI provides a singular front-end to any number of individual packages that contain one or more commands. Each command maps 1:1 with an executable file that is called by Akamai CLI. You can create these executables in any language, with full support for Go, Python, and JavaScript.

Naming conventions

Name each executable you create either akamai-<command> or akamai<Command> and include it in the repository root or bin subdirectory. Regardless of what option you choose, try to stay consistent throughout your project.

When naming a command:

  • Follow the principle of least surprise. Use a descriptive name to clearly communicate the purpose and result of a command. 

  • Try to avoid acronyms, unless they are widely known ones, such as HTTPS or json. However, if the name is overly long or tricky to type (such as “prioritization”), then it’s best to add an alias. For example, for visitor-prioritization, use the vp alias.

User input

Check the guidelines for each type of user input the CLI commands may require.

Flags

Prefix each flag with a double hyphen --. If a flag consists of more than one word, separate them with a single hyphen -. For example:

  • --edgerc

  • --from-version

  • --output-file

Arguments

Arguments are unnamed positional values. Try to use them sparingly, and require them only as variadic input at the end.

For example, see the last argument for akamai purge that stands for any number of URLs to purge:



$ akamai purge invalidate https://example.org/ https://example.org/about https://example.org/contact-us

 

Interactive input

You can create commands that run interactively, asking users a series of questions to help them accomplish their task. To allow users to fully execute a command, provide an option that answers all questions the same way. 

To guide your users through the process, create brief and clear prompts. Ideally, provide a default response when applicable. For example:

Save output to [./data/foo]:

If the prompt has a set of possible answers, indicate the default one using uppercase or bold text:

Are you sure? [y/n]:

or:

What would you like to do? (S)ave/(v)iew/(d)iscard:

 

Overriding confirmations

It is a general practice to ask users to confirm destructive or irrevertible actions. However, remember to provide a --force flag in your custom package to allow users to explicitly override the confirmations.

Environment variables

Make the environment variables upper case and prefix each with AKAMAI_, followed by the package name and the flag name. For example, AKAMAI_PROPERTY_CLONE is an environment variable for the Property Manager CLI --clone flag. If you want to provide environment variables for positional (unnamed) parameters, use a meaningful descriptive name, for example, AKAMAI_PROPERTY_HOSTNAME.

API credentials

If any of the custom commands uses Akamai OPEN APIs, make sure your package supports authentication with the .edgerc file. For this purpose, use one of our official signing libraries that implement Akamai EdgeGrid Authentication scheme and environment variables out of the box.

Additionally, support the following optional flags:

Flag

Description

Example

Default

--edgerc

The full path to the .edgerc file.

/etc/akamai/.edgerc

$HOME/.edgerc

--section

A section of the .edgerc file with credentials to use.

my-app

The same as the command name (e.g. purge).

 

Other secure input

If your commands require other credentials or secure configuration beyond the --edgerc and --section flags, ask the users to provide secure values in environment variables or interactive input. Don’t use flag values for this purpose, such as --password=MYPASSWORD

It’s best to implement both environment variables and interactive input. If a flag is used to pass secure credentials, the interactive input should have priority over any environment variables:



$ export AKAMAI_EXAMPLE_PASSWORD=foobar

$ akamai example --password

Enter your password: # this input will override the environment variable 

Note: Prompts shouldn’t show any output while users input secure data.

Output

All regular output should be sent to STDOUT. All errors and other out-of-band data, such as progress information, should be sent to STDERR.

For errors, create user-friendly messages that explain why the problem occurred and how to fix it. Don’t output raw errors, such as uncaught exceptions or stack traces.

To indicate that a command or task is processing, use spinners, progress bars, or any similar devices.

 

Color conventions

Use colors to improve readability and clarity of your output in Akamai CLI.

Adhere to the conventions below for consistent user experience across packages. The following list uses the ANSI color names and may show differently on a local terminal:

  • Headers should be yellow

  • Success messages should be green

  • Errors should be red

  • Warnings should be cyan

 

Colors effectively draw users’ attention, but try to keep it to no more than two additional colors outside of the above list. If necessary, you may also use bright variants, bold, and underline to further differentiate the output.

Status messages

For reporting task statuses, use the following format:

Attempting to fetch command...... [<STATUS>]

Installing...... [<STATUS>]

Where <STATUS> is one of:

  • Success – green OK

  • Warning – cyan WARN

  • Failure – red FAIL

If the status is other than OK, make sure you provide a relevant error or warning message. User-friendly messages give a clear idea of the problem and how to resolve it:

Attempting to fetch command...... [OK]

Installing...... [FAIL]

Unable to locate Node.js runtime

JSON output

You may choose to include a JSON output mode for your commands. It allows you to pipe the output to a file for further processing, or process it through an additional utility, such as jq.

To enable this mode, use the --json flag or AKAMAI_OUTPUT_JSON environment variable.

 

Scripting

Build actions in a way that makes them composable, rather than all-encompassing.

With this in mind, see sample actions for hosts:

$ HOST=example.org

$ akamai cert create $HOST | akamai property add-cert $HOST && akamai property activate $HOST --network PROD 

Note: This example was created only for documentation purposes.

Package documentation

Each of your packages needs to include README.md and LICENSE documentation files. You can use the following template to cover all necessary information.

Akamai CLI for <package_name>

Here, provide a brief introduction to your custom package.

Installation

Guide users through the installation process. Include all available installation options, such as Akamai CLI package manager, binary, or compiling from source. Wrap the commands in code blocks, for example:

$ akamai install <package>

Functionality

Explain the purpose of the package and list basic functionalities:

  • Functionality #1

  • Functionality #2

Usage

Provide a usage example:

$ akamai <command> [command flags] <action> [--important-flag] [positional arguments]

Actions

Here, provide a list of actions with brief descriptions, like the ones from akamai <command> help. Link each action to a separate section that covers it in more detail.

Action name

Describe each action, including:

Flags

--list         Description

--of           Description

--flags        Description

Examples

Provide action examples. Make sure that shell command examples start with a $ prompt.   

$ akamai action example

Note: While writing documentation, use example.com, example.org, or example.net for all hostnames (see IANA).