CLI style guide
User experience is at the core of Akamai CLI. Follow our best practices to create consistent and user-friendly custom commands.
Name each executable you create either
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
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
Check the guidelines for each type of user input the CLI commands may require.
Prefix each flag with a double hyphen
--. If a flag consists of more than one word, separate them with a single hyphen
-. For example:
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
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]:
What would you like to do? (S)ave/(v)iew/(d)iscard:
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.
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,
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:
The full path to the
A section of the
The same as the command name (e.g.
Other secure input
If your commands require other credentials or secure configuration beyond the
--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
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.
All regular output should be sent to
STDOUT. All errors and other out-of-band data, such as progress information, should be sent to
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.
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.
For reporting task statuses, use the following format:
Attempting to fetch command...... [<STATUS>]
<STATUS> is one of:
Success – green
Warning – cyan
Failure – red
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]
Unable to locate Node.js runtime
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.
Build actions in a way that makes them composable, rather than all-encompassing.
With this in mind, see sample actions for hosts:
$ akamai cert create $HOST | akamai property add-cert $HOST && akamai property activate $HOST --network PROD
Note: This example was created only for documentation purposes.
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.
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>
Explain the purpose of the package and list basic functionalities:
Provide a usage example:
$ akamai <command> [command flags] <action> [--important-flag] [positional arguments]
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.
Describe each action, including:
Provide action examples. Make sure that shell command examples start with a $ prompt.
$ akamai action example
Note: While writing documentation, use
example.net for all hostnames (see IANA).