The CLI is a downloadable utility you can use to control EdgeKV functionality. It lets you administer EdgeKV without writing code against Akamai’s administrative APIs, or using the Akamai Control Center UI. The CLI also enables you to script EdgeKV behaviors.

You can issue commands to trigger activities including database initialization, namespace management, token creation, and CRUD operations.

The EdgeKV CLI is part of the EdgeWorkers CLI package. For more information about the installation process see the EdgeWorkers CLI instructions and the EdgeKV CLI instructions.

👍
Please pay attention to the prerequisites section in the installation instructions.

Validate the CLI version

Use this command to validate that you have EdgeKV CLI version 1.2.1 or later.

akamai edgekv --version

Update the EdgeWorkers CLI

If you already use the EdgeWorkers CLI, you need to use this command to get the latest EdgeKV CLI capabilities.

akamai update edgeworkers

Initialize EdgeKV

Let’s initialize EdgeKV itself with the init command. This is a one-time operation performed when starting to use EdgeKV for the first time.

akamai edgekv init

Here's the sample output:

----------------------------------
--- EdgeKV already INITIALIZED ---
----------------------------------
AccountStatus ProductionStatus StagingStatus Cpcode
------------- ---------------- ------------- -------
INITIALIZED   INITIALIZED  	   INITIALIZED   123456

Check namespace initialization status

The initialization usually completes within one minute. You can review the status of the database at any time with the show status command.

Once AccountStatus, ProductionStatus, and StagingStatus are INITIALIZED, you can start using your namespace.

📘
You can use EdgeKV in both staging and production environments, and manage databases in each environment separately.

akamai edgekv show status

Here's the sample output:

----------------------------------
--- EdgeKV already INITIALIZED ---
----------------------------------
AccountStatus ProductionStatus StagingStatus Cpcode
------------- ---------------- ------------- -------
INITIALIZED   INITIALIZED      INITIALIZED   123456

List namespaces

As part of the initialization step, a default namespace is automatically created in both staging and production environments.

Check that this namespace exists in the staging environment by listing available namespaces in the environment.

akamai edgekv list ns staging

Here's the sample output:

---------------------------------------------------------------------------
--- The following namespaces are provisioned on the staging environment ---
---------------------------------------------------------------------------
Namespace
---------
default

Create a namespace

Next, we want to create a new namespace called "test" in the staging environment, and set its retention period to 90 days. This namespace will be separate from the default namespace we previously created, and will be the target for our data. The retention period determines how long data is kept in the namespace before being automatically deleted. Retention period is denominated in days, and can be set to zero for an indefinite retention period. Once set, the lifespan of data in the namespace is updated whenever a data value is added or changed. Any change to retention period will ONLY apply to newly-written or updated data; existing data will continue to use the previous retention period.

The GeoLocation data defaults to US, but will be changeable in the future.

akamai edgekv create ns staging test --retention 90

Here's the sample output:

----------------------------------------------------------------------------------
--- Namespace test has been created successfully on the staging environment ---
----------------------------------------------------------------------------------
Namespace RetentionPeriod       	 GeoLocation
--------- -------------------------  -----------
test  	  2 months 29 days (90days)  US

Verify the namespace

Verify that the namespace you just created exists on staging.

akamai edgekv show ns staging

Here's the sample output:

---------------------------------------------------------------
--- The following namespaces are provisioned on the production environment ---
---------------------------------------------------------------
Namespace
---------
default
test

List namespace details

To get details about the attributes of your namespace, such as RetentionPeriod and GeoLocation, use the --details command.

akamai edgekv list ns staging --details

Here's the sample output:

------------------------------------------------------------------------------
--- The following namespaces are provisioned on the staging environment ---
------------------------------------------------------------------------------
Namespace     	    RetentionPeriod         	    GeoLocation  	GroupId
----------------  	--------------------------  	-----------  	-------
default           	6 months (182days)            US       	    0
test              	2 months 29 days (90days)     US      	    0

Add a text item

Let's add some data to the test namespace on staging. Data in a namespace is contained inside a container called a group. If a group does not already exist, it must be created when uploading data into a namespace, otherwise just add the group name. In the example below, the group does not exist, so we add the name “testgrp” to our write operation. You can learn more about groups by reviewing our data model.

akamai edgekv write text staging test testgrp key1 "This is the value of key1"

Here is the sample output:

--------------------------------------------------------------------------------------------------------------
--- Item key1 was successfully created into the environment: staging, namespace: test and groupid: testgrp ---
--------------------------------------------------------------------------------------------------------------

Add a JSON item

Let's do the same thing, but this time instead of writing text, write a json file to the same testgrp group. You can use key2 and point to the local json.txt file for the JSON value to write.

This command imports the JSON.

cat /tmp/json.txt
{
"x": "1",
"y": [1,2]
}

This command validates it and stores it as the value for key2.

akamai edgekv write jsonfile staging test testgrp key2 /tmp/json.txt

Here's the sample output:

--------------------------------------------------------------------------------------------------------------
--- Item key2 was successfully created into the environment: staging, namespace: test and groupid: testgrp ---
--------------------------------------------------------------------------------------------------------------

List the keys from the test namespace

Now that you've added two unique key value pairs to the testgrp group, you can list them.

Here, you're listing the items from the testgrp group and the test namespace on staging.

📘
This operation is limited to retrieving a maximum number of 100 items. For details see Limits.

akamai edgekv list items staging test testgrp

Here's the sample output:

---------------------------------------------------------------
--- 2 items from group testgrp were retrieved successfully. ---
---------------------------------------------------------------
key1
key2

Read values for an item

Use the read item command to read back the value of the key.

The response for key1 includes the text value previously input. In this example, you are reading key1 from the group testgrp contained in the test namespace on the staging network:

akamai edgekv read item staging test testgrp key1

Here's the sample output:

----------------------------------------------------------------------------------------------------
--- Item key1 from group testgrp, namespace test and environment staging retrieved successfully. ---
----------------------------------------------------------------------------------------------------
This is the value of key1

Here, you're reading from the test namespace on staging and retrieving key2 from the testgrp group. The response for key 2 includes the nested JSON you previously stored.

akamai edgekv read item staging test testgrp key2

Here's the sample output:

----------------------------------------------------------------------------------------------------
--- Item key2 from group testgrp, namespace test and environment staging retrieved successfully. ---
----------------------------------------------------------------------------------------------------
{"x":"1","y":[1,2]}

Delete an item

Use the delete item command against a specific key. Here, you're deleting key2 on staging.

akamai edgekv delete item staging test testgrp key2

Here's the sample output:

-----------------------------------------------------------------------------------------------------------------
--- Item key2 was successfully marked for deletion from group testgrp, namespace test and environment staging ---
-----------------------------------------------------------------------------------------------------------------

To make sure that the item is no longer in testgrp, run the list items command.

akamai edgekv list items staging test testgrp

Here is the sample output showing that only key1 remains in the group testgrp group on staging:

---------------------------------------------------------------
--- 1 items from group testgrp were retrieved successfully. ---
---------------------------------------------------------------
key1

To confirm again that key2 is no longer in testgrp, run the read item command.

akamai edgekv read item staging test testgrp key2

Here's the sample output showing that key2 has been deleted.

ERROR: Unable to read item.