Command Line Interface (CLI)

There are a handful of ways to interact with the Akeyless Vault Platform for managing, creating, and fetching multiple types of supported secrets. One of them is our Command Line Interface (CLI), which is purpose-built to serve your custom automation scripts (usually within a CI/CD pipeline or backup process), as well as human DevOps/Software engineers. For a full list of the available CLI command, see the CLI reference.

Akeyless Vault CLI has a pre-compiled binary version for Linux, macOS, and Windows which can be easily installed.

Download and Install

If you don’t already have an Akeyless account, register for an account with Akeyless Vault Platform here.

πŸ‘

Zero Knowledge with Akeyless CLI

In case you are working with your own Fragment, please create the following environment variable to point your CLI to interact with the relevant Gateway:

For Linux OS use:

export AKEYLESS_GATEWAY_URL=<https://Your_GW_URL:8080>

For Windows OS use:

set AKEYLESS_GATEWAY_URL=<https://Your_GW_URL:8080>

Run the following command to download and install the CLI binary.

curl -o akeyless https://akeyless-cli.s3.us-east-2.amazonaws.com/cli/latest/production/cli-linux-amd64
chmod +x akeyless
./akeyless
curl -o akeyless https://akeyless-cli.s3.us-east-2.amazonaws.com/cli/latest/production/cli-linux-arm64
chmod +x akeyless
./akeyless
curl -o akeyless https://akeyless-cli.s3.us-east-2.amazonaws.com/cli/latest/production/cli-darwin-amd64
chmod +x akeyless
./akeyless
curl -o akeyless https://akeyless-cli.s3.us-east-2.amazonaws.com/cli/latest/cli-darwin-arm64
chmod +x akeyless
./akeyless
curl -o akeyless.exe https://akeyless-cli.s3.us-east-2.amazonaws.com/cli/latest/production/cli-windows-amd64.exe
akeyless.exe

To pull the latest CLI version from the Akeyless official bucket, please make sure the following endpoint is trusted:

https://akeyless-cli.s3.*

Or using Homebrew package manager for MacOS:

brew install akeylesslabs/tap/akeyless

Authenticate

At the first time you run any command, the CLI will prompt you to authenticate to Akeyless.

πŸ“˜

Tip

to initiate the CLI non-interactively, run: ./akeyless --init (only relevant the first time you run it)

πŸ“˜

Note

PowerShell ISE does not support interactive input mode. Please work with the PowerShell cmdlet to set up the Akeyless CLI.

To work directly with Akeyless SaaS services, use the Default URL vault.akeyless.io.

At the prompt Would you like to configure a profile (Y/n) line, type Y. Then, type a name to rename the default profile, or press Enter to leave the name as default.

You can configure various types of authentication methods from the CLI:

  1. API Key (access_key)
  2. AWS IAM (aws_iam)
  3. Azure Active Directory (azure_ad)
  4. SAML (saml)
  5. Password (email/password)
  6. OIDC (oidc)
  7. K8s (k8s)
  8. GCP (GCP)

For more information about authentication methods, see Authentication Methods.

For example, you can use your email & password or an API Key.

akeyless configure --admin-email yourEmailAddress
#configure a profile
akeyless configure
Access ID:  p-abc12de
Access Key: <Your Access Key>
Profile default successfully configured

🚧

Note:

If you don’t enter the correct credentials, for security reasons, the Akeyless CLI will not give you an error message. An error message will be received when you attempt to run commands.

From this point until the end of the installation, the process looks different depending on your OS.

Finishing the Installation on Windows

After configuring your profile, the following prompt will appear:

Would you like to move 'akeyless.exe' binary to: C:\Users\username\.akeyless\bin\akeyless.exe? (Y/n)
#after user inputs 'Y'
The cli was successfully moved to path: C:\Users\username\.akeyless\bin\akeyless.exe

After the Akeyless CLI Binary is moved to USER_HOME_DIR/.akeyless/bin/akeyless, another prompt will appear:

Would you like to add 'C:\Users\username\.akeyless\bin' To user PATH environment variable? (Y/n)
#after user inputs 'Y'
Run the following command to start using Akeyless CLI:
set "PATH=%PATH%;C:\Users\username\.akeyless\bin" (Update PATH for current session)
setx PATH "%PATH%;C:\Users\username\.akeyless\bin" (Update PATH permenantly)

πŸ“˜

Note

The CLI updates the path env for the current user only. This change only takes effect after the user logs off and logs back on.

Copy the relevant command for your purpose (permanent or session only) and run it.
After this, you are ready to use the CLI.
Try running the create-secret command to test your installation:

akeyless create-secret --name MySecret1 --value MySecretPassword

Finishing the Installation on Linux\Mac

After configuring your profile, the following prompt will appear:

Would you like to move 'akeyless' binary to: /home/username/.akeyless/bin/akeyless? (Y/n) 
#after user inputs 'Y'
The cli was successfully moved to path: /home/username/.akeyless/bin/akeyless

After the Akeyless CLI Binary is moved to USER_HOME_DIR/.akeyless/bin/akeyless, another prompt will appear:

Would you like to add '/home/username/.akeyless/bin' To user PATH environment variable? (Y/n)

After inputting Y the CLI will try to locate the user profile file (based on shell, i.e '.bash_profile', '.zprofile', '.profile', etc), and export the USER_HOME_DIR/.akeyless/bin/ to user $PATH. If Akeyless can't find your user profile file you will have to export the path yourself.
After successfully updating the path, the following prompt will appear:

Please run the following command to start using Akeyless CLI:
	'source ~/.bash_profile'

After you run the command, The CLI should be ready to use.
Try running the create-secret command to test your installation:

akeyless create-secret --name MySecret1 --value MySecretPassword

Working with Profiles

Akeyless has the option to work with profiles. Different profiles can be linked with different authentication methods, and from there also linked with different permissions associated with them.
As described above, the default profile is set up when you first open the CLI, and will be used to perform any command until more profiles are configured.
To see which profiles exist on your machine, go to the .akeyless folder that was created on your machine during the installation, it should be located in your home folder on Linux or under your <username> folder in Windows.
Under the .akeyless folder you will see a folder named profiles, within there is a TOML file for each profile.

If you wish to configure a new profile, use the following command:

akeyless configure --profile <profile name> --access-id <Access id> --access-key <Access key> --access-type access_key

While the default method is an API access key, if you wish to use a different authentication method please consult the CLI reference for this command.

After you've created an additional profile, simply add the --profile parameter with the profile name to any akeyless command to perform it from that profile.

Troubleshooting

If you are trying to perform an action with a certain platform and are denied access, it is important you check the two following settings:

  • Permissions: Make sure the authentication method you created the profile with is associated with the proper role that has the authority to perform the action you tried.
  • Profile TOML: As discussed in the following section, creating a profile will create a corresponding TOML file. The general structure of these files, if opened in a text editor, is:
["<profile name>"]
  access_id = '<Access ID>'
  access_type = 'access_key'
  access_key = '<Access Key>'

The parameters may change based on your access type. In the file, you may check that everything is spelled correctly and matches the authentication method you chose.