CLI Documentation

Custom Packages

You can go beyond the pre-defined features by building your own packages to use with Akamai CLI. Follow the architecture guidelines & release best practices below to ensure smooth integration and consistent user experience.

For a list of considerations, you should take into account while building custom commands, see CLI style guide.

Package architecture

Libraries

Regardless of the language you choose to build a custom package, make sure you implement each function as a stand-alone library. This way, you can use the libraries independently of the CLI.

Supported languages

Akamai CLI supports packages built with the following languages:

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

Dependencies

Akamai CLI automatically installs dependencies based on the package manager configuration for a specific language:

If you decide not to use any of these package managers, make sure you vendor all dependencies in your project repository.

API credentials

If any of the commands in your package uses Akamai OPEN APIs, make sure to support authentication with the .edgerc file. See CLI style guide for more information.

Caching

You can enhance Akamai CLI’s responsiveness by caching data, especially API requests. Akamai CLI exports the AKAMAI_CLI_CACHE_PATH environment variable with the current location of the cache directory. For your custom packages, use the following directory structure for caching purposes:

• Store the API responses in sub-directories that indicate the applicable.edgerc credentials section and the API endpoint path: $AKAMAI_CLI_CACHE_PATH/api/<Edgerc section>/<API URL path>

• Store the package-specific caching data in the sub-directory with a matching name: $AKAMAI_CLI_CACHE_PATH/package/<package name>

Configuration file

Akamai CLI maintains the INI configuration file in the $AKAMAI_CLI_HOME/config directory.

For every custom package, add a section with a matching name to the configuration file. For example, for the purge package, add:

[purge]

network = "staging"

Note: The [cli] section is reserved for Akamai CLI, no other package may modify that section.

In your sections, keep keys human-readable and use hyphens - to separate words.

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

Package Metadata

To inform Akamai CLI about the custom package, create a cli.json file. This is where you specify the command language runtime version and define all commands included in the package.

Format

• requirements: Specifies runtime requirements. You may specify a minimum version number or use the * wildcard for any version. Possible requirements are:

  • go

  • node

  • python

• commands: Lists 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.

  • version: The command version.

  • description: A short description for the command.

  • bin: A URL to fetch a binary package from if it cannot be installed from source.
    The bin URL may contain the following placeholders:

    • {{.Version}}: The command version.

    • {{.Name}}: The command name.

    • {{.OS}}: The current operating system, either windows, mac, or linux.

    • {{.Arch}}: The current OS architecture, either 386 or amd64.

    • {{.BinSuffix}}: The binary suffix for the current OS: .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/{{.Version}}/akamai-{{.Name}}-{{.OS}}{{.Arch}}{{.BinSuffix}}"

    }

  ]

}

Releases

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

Branches

Make sure that the master branch in Git is usable at all times. This is the code that your package will run.

All your development should occur in feature or version branches:

Tag each of you releases with a version number, and add the release notes with Github’s releases feature: 

Binaries

In addition to running from source code, you can also use a pre-compiled binary for setting up your custom package. If the language you selected to create your package supports binaries, the language runtime becomes optional.

If you plan to release binaries, perform the following:

• Attach the binary files to the Github release. Akamai CLI automatically finds the latest release and downloads the binaries using the URL indicated in the packages cli.json (see: Package Metatadata).

• For every binary, create a .sig file with the corresponding name. It should only contain the sha256 checksum for the file. Akamai CLI automatically verifies whether the signatures match and the binary file is not corrupt.

• Use code signing to ensure that the binaries can run in restricted environments on macOS and Windows.

Updates

akamai update [package] command checks out the latest version of the master branch, and downloads the latest package. This option works both for the source code and binaries. You can also configure Akamai CLI to automatically check for updates.

Versions

Akamai CLI packages must adhere to semantic versioning (SemVer).

The first release for a package should be version 0.1.0.