EdgeWorkers CLI
EdgeWorkers CLI The EdgeWorkers command line interface (CLI) expedites the process of registering, uploading, activating and testing EdgeWorkers functions on the Akamai Edge network.
Go to Akamai CLI for EdgeKV for information on how to manage EdgeKV databases and call the EdgeKV API from the command line.
Technical Setup Requirements
To use this tool you need:
- Akamai CLI installed.
- Valid EdgeGrid credentials configured via Akamai Control Center (see Get Started with APIs)
- Node version 14 or higher
Install or Update the EdgeWorkers
- If you do not have the EdgeWorkers CLI package installed, use the following Akamai CLI command to install the latest EdgeWorkers CLI package:
Usage:
akamai install edgeworkers
- If you already have the CLI installed, use the following Akamai CLI command to install the latest EdgeWorkers CLI package that includes EdgeKV functionality:
Usage:
akamai update edgeworkers
Overview of Commands
EdgeWorkers CLI enables you to manage EdgeWorkers functions by calling the EdgeWorkers API.
Conventions:
- optional args
[] - required args
<>
Usage:
akamai edgeworkers [options] [command]
Options:
| Syntax | Description |
|---|---|
| -V, –version | Display the version number for the EdgeWorkers CLI program. |
| –debug | Show debug information. |
–edgerc <path> |
Use credentials in edgerc file for command. (Default file location is ~/.edgerc) |
–section <name> |
Use this section in edgerc file. (Default section is [default]) |
–timeout <timeout> |
You can specify a timeout value for a command in seconds to override the 2 minute default. For example, if you add “–timeout 10” to a command, it will timeout if the server takes more than 10 second to respond. |
–json [path] |
Write CLI output as JSON to optionally provided path. If not path provided, write JSON output to CLI home directory |
| -h, –help | Display usage information for EdgeWorkers CLI. |
Commands:
| Command | Alias | Description |
|---|---|
help [command] |
Display usage information for the given command. |
list-groups | lg [group-identifier] |
Customer Developer can find their EdgeWorkers access level per Luna Access Control Group. |
list-ids | li [options] [edgeworker-identifier] |
List EdgeWorker ids currently registered. |
register | create-id <group-identifier> <edgeworker-name> |
Register a new EdgeWorker id to reference in Property Manager behavior. |
update-id | ui <edgeworker-identifier> <group-identifier> <edgeworker-name> [options] |
Allows Customer Developer to update an existing EdgeWorker Identifier’s Luna ACG or Name attributes. |
delete-id | delete-id [options] <edgeworker-identifier> |
Permanently delete an existing EdgeWorker Id. |
list-versions | lv <edgeworker-identifier> [version-identifier] |
List Version information of a given EdgeWorker Id. |
upload | create-version [options] <edgeworker-identifier> |
Creates a new version of a given EdgeWorker Id which includes the code bundle. |
delete-version | delete-version [options] <edgeworker-identifier> <version-identifier> |
Permanently delete an existing version of a given EdgeWorker Id. |
download | download-version [options] <edgeworker-identifier> <version-identifier> |
Download the code bundle of an EdgeWorker version. |
status | list-activations [options] <edgeworker-identifier> |
List Activation status of a given EdgeWorker Id. |
activate | av <edgeworker-identifier> <network> <versionId> |
Activate a Version for a given EdgeWorker Id on an Akamai Network. |
deactivate | deact <edgeworker-identifier> <network> <versionId> |
Deactivate a Version for a given EdgeWorker Id on an Akamai Network. |
validate | vv <bundlePath> |
Validates a code bundle version without uploading the code bundle. |
create-auth-token | auth [options] <hostName> |
Generates an authentication token that can be used to get detailed EdgeWorker debug response headers. |
generate-secret | secret [options] |
Generates a secret key that can be used to generate auth token or in property variable. |
clone | clone <edgeworker-identifier> <resourceTierId> [options] |
Clones an Edgeworker from the existing Edgeworker Id. |
list-contracts | li-contracts [options] |
List of contract ids that user has access to. |
list-properties | lp <edgeworker-identifier> [options] |
List of properties associated with a given EdgeWorker Id. |
list-restiers | li-restiers [options] |
List Resource Tiers that can be used to create or clone EdgeWorker Id. |
show-restier | show-restier <edgeworker-identifier> |
Customers can get Resource Tier details for a specific EdgeWorker Id. |
List Permission Groups with EdgeWorkers Access
Customer Developer can find their EdgeWorkers access level per Luna Access Control Group.
Usage: akamai edgeworkers list-groups [options] [group-identifier]
| Option | Description |
|---|---|
| -h, –help | output usage information |
| Argument | Existence | Description |
|---|---|---|
| group-identifier | optional | Luna Access Group value (usually number) to check for EdgeWorkers permissions |
Key Details
-
Output is filtered to only those Luna Access Control Groups that have at least one EdgeWorkers capability.
-
Capabilities can be: VIEW,VIEW_VERSION,EDIT,VIEW_ACTIVATION,CREATE_VERSION,ACTIVATE
List Existing EdgeWorker Identifiers
List EdgeWorker ids currently registered.
Usage: akamai edgeworkers list-ids [options] [edgeworker-identifier]
| Option | Description |
|---|---|
| -h, –help | output usage information |
–groupId <groupId> |
Filter EdgeWorker Id list by Permission Group |
–resourceTierId <resourceTierId> |
Filter Edgeworker Id by Resource Tier |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | optional | A unique integer handle to an EdgeWorkers instance |
Register New EdgeWorker Identifier
Register a new EdgeWorker id to reference in Property Manager behavior.
Usage: akamai edgeworkers register [options] <group-identifier> <edgeworker-name>
| Option | Description |
|---|---|
| –resourceTierId | New Resource tier id to which the Edgeworker will be associated. |
| -h, –help | output usage information |
| Argument | Existence | Description |
|---|---|---|
| group-identifier | required | Luna Access Group value (usually number) to check for EdgeWorkers permissions |
| edgeworker-name | required | Human readable short label describing an EdgeWorkers instance |
Key Details
-
Location response header will be provided with new EdgeWorker Id.
-
EdgeWorker id details response body (JSON) will be provided with 201 response code.
-
To disable prompts for automation purpose “resourceTierId” can be provided as input.
Update EdgeWorker Identifier’s Information
Allows Customer Developer to update an existing EdgeWorker Identifier’s Luna ACG or Name attributes.
Usage: akamai edgeworkers update-id [options] <edgeworker-identifier> <group-identifier> <edgeworker-name>
| Option | Description |
|---|---|
| –resourceTierId | New Resource tier id to which the Edgeworker will be associated |
| -h, –help | output usage information |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | required | A unique integer handle to an EdgeWorkers instance |
| group-identifier | required | Luna Access Group value (usually number) to check for EdgeWorkers permissions |
| edgeworker-name | required | Human readable short label describing an EdgeWorkers instance |
Key Details
-
API requires that both groupId and name be provided even if only changing one of these attributes.
-
EdgeWorker id details response body (JSON) will be provided with 200 response code.
-
Resource Tier ID provided should be same as the one the EdgeWorker ID already has. In order to provide a different resource tier id, please use the clone operation.
Delete Existing EdgeWorker Identifier
Permanently delete an existing EdgeWorker Identifier.
Usage: akamai edgeworkers delete-id [options] <edgeworker-identifier>
| Option | Description |
|---|---|
| -h, –help | output usage information |
| –noPrompt | Skip the deletion confirmation prompt |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | required | A unique integer handle to an EdgeWorkers instance |
Key Details
-
Deleting an EdgeWorker ID is only possible if it doesn’t have any version currently active or being activated on the Akamai network.
-
Ensure that there are no active properties associated with an EdgeWorker before deletion.
List EdgeWorker Versions
List Version information of a given EdgeWorker Id.
Usage: akamai edgeworkers list-versions [options] <edgeworker-identifier> [version-identifier]
| Option | Description |
|---|---|
| -h, –help | output usage information |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | required | A unique integer handle to an EdgeWorkers instance |
| version-identifier | optional | A unique integer handle to version of an EdgeWorkers instance |
Key Details
-
Result set is sorted by an upload sequence value that is not displayed (an internal incremented integer).
-
EdgeWorker versions are customer defined strings.
Upload New EdgeWorker Version
Creates a new version of a given EdgeWorker Id which includes the code bundle.
Usage: akamai edgeworkers upload [options] <edgeworker-identifier>
| Option | Description |
|---|---|
| -h, –help | output usage information |
–bundle <bundlePath> |
Path to bundle file in tgz format |
–codeDir <workingDirectory> |
Working directory that includes main.js and bundle.json files |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | required | A unique integer handle to an EdgeWorkers instance |
Key Details
-
One of either
--bundleor--codeDir(but not both) must be provided. -
Code bundles paths and files must be found on the local filesystem.
-
--bundleexpects a tgz file already built per EdgeWorkers specification. -
--codeDirexpects a directory path which contains both the main.js (events file) and bundle.json (manifest file). -
--codeDiroption will provide bundle.json format validation. -
--codeDirdoes not pack other directories or code beyond main.js and bundle.json. -
--codeDirwill build the tarball (tgz) file if file validation succeeds. -
Service will compare new tarball’s checksum with previously uploaded tarballs for the same EdgeWorker id (
ewId). If a match is found, the new version creation is disallowed. -
versionIdis customer generated and will be pulled from bundle.json. -
Location response header will be provided with new EdgeWorker Version id.
-
EdgeWorker version details response body (JSON) will be provided with 201 response code.
Delete Existing EdgeWorker Version
Permanently delete an existing version of a given EdgeWorker Id.
Usage: akamai edgeworkers delete-version [options] <edgeworker-identifier> <version-identifier>
| Option | Description |
|---|---|
| -h, –help | output usage information |
| –noPrompt | Skip the deletion confirmation prompt |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | required | A unique integer handle to an EdgeWorkers instance |
| version-identifier | required | A unique integer handle to version of an EdgeWorkers instance |
Key Details
-
Deleting a version is only possible if it is not currently active or being activated on the Akamai network.
-
If the version is currently active, it will have to be deactivated before it can be deleted.
Download an EdgeWorkers Code Bundle
Download the code bundle of an EdgeWorker version.
Usage: akamai edgeworkers download [options] <edgeworker-identifier> <version-identifier>
| Option | Description |
|---|---|
| -h, –help | output usage information |
–downloadPath <downloadPath> |
Path to store downloaded bundle file; defaults to CLI home directory if not provided. |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | required | A unique integer handle to an EdgeWorkers instance |
| version-identifier | required | A unique integer handle to version of an EdgeWorkers instance |
Key Details
- If
--downloadPathis not provided or is not found on local filesystem, an AkamaiCLI cache sub-directory will be used:<CLI_CACHE_PATH>/edgeworkers-cli/edgeworkers/<ewid>/
List EdgeWorker Version Activation Status
List Activation status of a given EdgeWorker Id.
Usage: akamai edgeworkers status [options] <edgeworker-identifier>
| Option | Description |
|---|---|
| -h, –help | output usage information |
–versionId <versionId> |
Version identifier |
–activationId <activationId> |
Activation identifier |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | required | A unique integer handle to an EdgeWorkers instance |
Key Details
- You may not provide both the Version and the Activation identifiers.
Activate an EdgeWorker
Activate a Version for a given EdgeWorker Id on an Akamai Network.
Usage: akamai edgeworkers activate [options] <edgeworker-identifier> <network> <version-identifier>
| Option | Description |
|---|---|
| -h, –help | output usage information |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | required | A unique integer handle to an EdgeWorkers instance |
| network | required | Label for which Akamai Network (STAGING or PRODUCTION) activation should be sent to |
| version-identifier | required | A unique integer handle to version of an EdgeWorkers instance |
Key Details
-
Network must be either STAGING or PRODUCTION. Capitalization will be normalized to uppercase.
-
Location response header will be provided with new EdgeWorker Activation id.
-
EdgeWorker activation details response body (JSON) will be provided with 201 response code.
Validate an EdgeWorkers Code Bundle
Validates a code bundle version without uploading the code bundle
Usage: akamai edgeworkers validate [options] <bundlePath>
| Option | Description |
|---|---|
| -h, –help | output usage information |
| Argument | Existence | Description |
|---|---|---|
| bundlePath | required | Path to bundle file in tgz format |
Key Details
-
Code bundle path must be found on the local filesystem.
-
Code bundle expects a tgz file already built per EdgeWorkers specification.
Deactivate an EdgeWorker
Deactivate a Version for a given EdgeWorker Id on an Akamai Network.
Usage: akamai edgeworkers deactivate [options] <edgeworker-identifier> <network> <version-identifier>
| Option | Description |
|---|---|
| -h, –help | output usage information |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | required | A unique integer handle to an EdgeWorkers instance |
| network | required | Label for which Akamai Network (STAGING or PRODUCTION) activation should be sent to |
| version-identifier | required | A unique integer handle to version of an EdgeWorkers instance |
Key Details
-
Network must be either STAGING or PRODUCTION. Capitalization will be normalized to uppercase.
-
Location response header will be provided with new EdgeWorker Activation id.
-
EdgeWorker activation details response body (JSON) will be provided with 201 response code.
Create an EdgeWorkers Authentication Token
Generates an authentication token that can be used to get detailed EdgeWorker debug response headers.
Usage: akamai edgeworkers create-auth-token [options] <hostName>
| Option | Description |
|---|---|
| -h, –help | output usage information |
–acl <aclPath> |
Path prefix of the response pages which require debugging |
–url <urlPath> |
Exact path of response page which requires debugging |
–expiry <expiry> |
Expiry duration of token, in minutes. |
–network <network> |
The Akamai environment on which to create this token, either “staging” or “production” |
–format <format> |
Format in which the output will be printed |
| Argument | Existence | Description |
|---|---|---|
| hostName | required | HostName of the property. Eg: www.test.com |
Key Details
-
The
--acland--urloptions are mutually exclusive to each other. -
The
--urlvalue is not explicitly part of the final token, but is used as a salt in the HMAC computation. -
The
--aclvalue can be a pattern that matches multiple pages, and is explicitly part of the final token. The default is/*. -
The
--expiryvalue must be between 1 and 720 minutes (12 hours). The default is15.
Generate a Random Secret Key
Generates a random secret key that can be used to create edgeworkers authentication token and in property PMUSER_EW_DEBUG_KEY.
Usage: akamai edgeworkers generate-secret
Clone an Edgeworker Id
Allows customer to clone an Edgeworker from an existing Edgeworker Id.
Usage: akamai edgeworkers clone <edgeworker-identifier> <resourceTierId> [options]
| Option | Description |
|---|---|
| -h, –help | output usage information |
| –ewName | Name of the Edgeworker |
| –groupId | Group identifier |
| Argument | Existence | Description |
|---|---|---|
| resourceTierId | required | Resource tier id to which the Edgeworker will be cloned. |
Key Details
- This endpoint allows user to select a different Resource Tier ID for a specific EdgeWorker id by cloning it. Cloning to the same resource tier will fail.
List Contracts
List of contract ids that user has access to.
Usage: akamai list-contracts
| Option | Description |
|---|---|
| -h, –help | output usage information |
List Properties
List of properties associated to a specific EdgeWorker Id.
Usage: akamai edgeworkers list-properties <edgeworker-identifier> [options]
| Option | Description |
|---|---|
| -h, –help | output usage information |
| –activeOnly | Returns only active properties |
| Argument | Existence | Description |
|---|---|---|
| edgeworker-identifier | required | Edgeworker identifier. |
Key Details
- Note that the returned boolean limitedAccessToProperties is true if the user doesn’t have access to the top level group under the account, or if they don’t have the admin role for this group.
List Resource Tiers for a specific Contract ID
Allows customers to list Resource Tiers that can be used to create or clone EdgeWorker IDs.
Usage: akamai list-restiers
| Option | Description |
|---|---|
| –contractId | Resource tiers for the specified contract id. |
| -h, –help | output usage information |
Key Details
- User will be prompted with list of contract ids that user has access to. The selected contract id will be used to fetch resource tier.
- To disable prompt for automation purpose, contract id can be provided as input.
Fetch the Resource Tier for a specific EdgeWorker Id
Customers can get Resource Tier details for a specific EdgeWorker Id.
Usage: akamai show-restier <edgeworkerId>
| Option | Description |
|---|---|
| -h, –help | output usage information |
| Argument | Existence | Description |
|---|---|---|
| edgeworkerId | required | Edgeworker identifier. |
Resources
For more information on EdgeWorkers, refer to the following resources:
Reporting Issues
You are all set, happy coding! If you experience any issues with the EdgeWorkers CLI, raise them as a github issue. Feel free to create a pull request with the fix or suggestion.