CLI Documentation

Library First

Regardless of which language you choose, all functionality should be implemented as a stand-alone library which can be used independently of the CLI.

Choosing a Language

We recommend using one of the following languages:

Note: All binaries must be code signed to work on restricted environments.

Dependency Management

Akamai CLI will automatically install dependencies when possible. It currently supports the following package managers:

If you are not using one of these package managers, then you must vendor all dependencies in your repository.

See the Akamai Style Guide for details.

In order to make the CLI as responsive as possible, you should cache as much as possible — in particular, API requests. Akamai CLI exports the AKAMAI_CLI_CACHE_PATH environment variable with the current location of the cache directory. Packages should use the following directory structure for caching:

• API responses should be stored using the endpoint path. Due to the way permissions can affect responses, they must be stored in a sub-directory for each credentials section: $AKAMAI_CLI_CACHE_PATH/api/<Edgerc section>/<API URL path>
• Package specific caching should be placed under a package specific sub-directory: $AKAMAI_CLI_CACHE_PATH/package/<package name>

Akamai CLI maintains a configuration file in $AKAMAI_CLI_HOME/config. The configuration file is in INI format.

Packages should add their own configuration under a section named after the package, e.g.:

[purge]

network = "staging"

Keys should be human-readable and use hyphens (-) to separate words.

Note: the [cli] section should be considered reserved for Akamai CLI, no other package may modify that section.

All configuration variables are made available via the environment as AKAMAI_CLI_{SECTION}_{KEY_NAME}, with hyphens replaced with underscores (_).

You must include a cli.json file to inform Akamai CLI about the package and it’s included commands.

cli.json allows you specify the command language runtime version, as well as define all commands included in package.

Format

• requirements — specify runtime requirements. You may specify a minimum version number or use * for any version. Possible requirements are:
  • go
  • php
  • ruby
  • node
  • python
• commands — An array of commands included in the package
  • name — The command name (used as the executable name)
  • aliases — An array of aliases that can be used to invoke the command (optional)
  • version — The command version
  • description — A short description of the command
  • bin — A url to fetch a binary package from if it cannot be installed from source (optional)

The bin URL may contain the following placeholders:

• {{.Version}} — The command version
• {{.Name}} — The command name
• {{.OS}} — The current operating system
  • Possible values are: windows, mac, or linux
• {{.Arch}} — The current OS architecture
  • Possible values are: 386, amd64
• {{.BinSuffix}} — The binary suffix for the current OS
• Possible values are: .exe for windows

Example

{

"requirements": {

    "go": "1.8.0"

  },

  "commands": [

{

    "name": "purge",

    "version": "0.1.0",

    "description": "Purge content from the Edge",

    "bin": "https://github.com/akamai/cli-purge/releases/download//akamai--"

   }

  ]

 }

Akamai CLI uses git as it's primary mechanism for retrieving a package for installation.

Version Control

Due to the use of git, you must ensure that the primary branch is usable at all times. This is the code that the package will run.

This means that all development should occur in feature or version branches:

Each release should be tagged with a version number, and release notes should be added using Github’s Releases feature: 

Binaries

In addition to running from source code, Akamai CLI can fall back to using a pre-compiled binary instead. This ability means that for languages that support it, the language runtime is not a requirement.

If you plan to release binaries, they should be attached to the Github release. Akamai CLI will automatically find the latest release and download those binaries. Binaries will be downloaded using the URL indicated in the packages cli.json by the bin key (see: Package Metatadata).

Binary Signing & Signature Files

Every binary file must be accompanied by a file of the same name with a .sig suffix that contains (only) the sha256 checksum for the file.

Akamai CLI will automatically verify that the signatures match when downloading.

Note: this is not a security feature, it only ensures that the binary file is not corrupt.

In addition, to ensure that the binaries can run on macOS and Windows platforms you should also use Code Signing to ensure that restricted environments will be able to execute the binary.

Updating

When akamai update [package] is called, the latest version of the primary branch is checked out, and if necessary the latest binary will be downloaded. In the future, Akamai CLI may pro-actively check for updates automatically, similar to Akamai CLI itself.

Akamai CLI packages must adhere to Semantic Versioning (AKA SemVer).

The first release for a package should be version 0.1.0.