Install the Akka CLI

The Akka CLI, akka, lets you interact with Akka projects, AI systems, local and remote Akka platform environments, governance bundles, and AI training runs. To install it, follow these steps:

Linux

Recommended approach

The recommended approach to install the akka CLI on Linux is using the Debian package repository:

curl -1sLf \
  'https://downloads.akka.io/setup.deb.sh' \
  | sudo -E bash
sudo apt install akka

If the akka CLI is already installed, and you want to upgrade to the latest version, you can run:

sudo apt update
sudo apt install --only-upgrade akka

Alternative approach

curl -sL https://doc.akka.io/install-cli.sh | bash

If that fails due to permission issues, use:

curl -sL https://doc.akka.io/install-cli.sh | bash -s -- --prefix /tmp && \
    sudo mv /tmp/akka /usr/local/bin/akka

You can pass options to the installer script with -s -- e.g.:

curl -sL https://doc.akka.io/install-cli.sh | bash -s -- --prefix=$HOME --version=3.0.77 --verbose
curl -sL https://doc.akka.io/install-cli.sh | bash -s -- -P $HOME -v 3.0.77 -V
macOS

Recommended approach

The recommended approach to install akka on macOS, is using brew

brew install akka/brew/akka

If the akka CLI is already installed, and you want to upgrade akka to the latest version, you can run

brew update
brew upgrade akka
Homebrew 7 and later require third-party taps to be trusted before installing or upgrading from them. If Homebrew warns that the akka/brew tap is not trusted, run brew trust --formula akka/brew/akka once and then retry.

Alternative approach

curl -sL https://doc.akka.io/install-cli.sh | bash

You can pass options to the installer script with -s -- e.g.:

curl -sL https://doc.akka.io/install-cli.sh | bash -s -- --prefix=$HOME --version=3.0.77 --verbose
curl -sL https://doc.akka.io/install-cli.sh | bash -s -- -P $HOME -v 3.0.77 -V
Windows

Recommended approach

The recommended approach to install the akka CLI on Windows is using winget:

winget install Akka.Cli

If the akka CLI is already installed, and you want to upgrade to the latest version, you can run:

winget upgrade Akka.Cli

Alternative approach

  1. Download the latest version of akka from https://downloads.akka.io/latest/akka_windows_amd64.zip

  2. Optionally, you can verify the integrity of the downloaded files using the SHA256 checksums.

  3. Extract the zip file and move akka.exe to a location on your %PATH%.

By downloading and using this software you agree to Akka’s Privacy Policy and Software Terms of Use.

Verify that the Akka CLI has been installed successfully by running the following to list all available commands:

akka help

You do not need to log in to use the CLI locally. Log in only to deploy to or manage a remote Akka Platform environment, whether it runs at akka.io or is installed in your enterprise. See Login to a remote env.

Check your version

Check regularly to ensure you have the latest version of the akka CLI. You can check the installed version by running:

akka version

Command structure

The general structure of an Akka CLI command is:

akka <command> [sub-command] [parameters] --[flags]

Flags, which modify command behavior, are always preceded by --. The flags that every command accepts are listed in CLI conventions.

Enable command completion

Completion allows you to hit [TAB] on a partially entered akka command and have the shell complete the command, subcommand or flag for you.

bash

To load completion in the current bash shell run:

source <(akka completion)

Configure bash to load akka completions for each session by adding the following line to your ~/.bashrc or ~/.profile file:

# add to ~/.bashrc or ~/.profile
source <(akka completion)

Using bash completions with akka requires you have bash completions enabled to begin with. Enable it in your ~/.bashrc or ~/.profile file with the following lines:

if [ -f /etc/bash_completion ]; then
  source /etc/bash_completion
fi

For definitive details on setting up your shell with auto-completion, see the shell documentation.
zsh (e.g. macOS)

To set up zsh shell completion run:

akka completion zsh > "${fpath[1]}/_akka"
compinit

If shell completion is not already enabled in your environment execute the following:

echo "autoload -U compinit; compinit" >> ~/.zshrc
fish

To set up fish shell completion run:

akka completion fish > ~/.config/fish/completions/akka.fish
source ~/.config/fish/completions/akka.fish
PowerShell

To set up shell completion for PowerShell run:

akka completion powershell | Out-String | Invoke-Expression

System configuration

The Akka CLI supports system-level configuration that allows administrators to customize CLI behavior across all users on a machine. This is useful for enterprise deployments where you want to control default settings, specify internal mirrors for templates, or disable certain features.

Configuration Options

The following settings can be configured at the system level:

Setting Description Default

code-templates-url

URL of project templates used by akka code init

https://doc.akka.io/_attachments/akka-code-init.json

context-url

URL of documentation context used by AI coding assistants

https://doc.akka.io/java/_attachments/akka-docs-md.zip

context-subdir

Subdirectory name where context files are stored

akka-context

additional-constitution-url

URL of an organization-specific constitution, downloaded and appended to the Akka SDK constitution at akka specify init

(none)

governance-policy-url

URL of the organization’s Akka Specify governance policy (policy.yaml — the organization’s mandatory exit conditions). Downloaded at /akka:setup and enforced by default; a developer’s --policy flag cannot loosen it. See Specify policies.

(none)

To disable a feature, set its value to none. For example, setting context-url to none disables automatic context downloading.

The last two settings are the organization’s governance controls for Akka Specify: additional-constitution-url extends the AI’s guidance, and governance-policy-url distributes the mandatory exit-condition policy. Both use the same managed channel as the template and context settings above, so IT deploys them the same way.

Configuration File Locations

The CLI looks for system configuration in platform-specific locations:

Linux
/etc/akka/config.yml
macOS

The CLI checks for configuration in this order:

  1. MDM-managed plist (preferred for enterprise deployments):

    /Library/Managed Preferences/io.akka.cli.plist

  2. YAML configuration file:

    /Library/Application Support/akka/config.yml

If an MDM plist is present, the YAML file is ignored.

Windows
%ProgramData%\akka\config.yml

Typically this resolves to C:\ProgramData\akka\config.yml.

YAML Configuration Format

Create a YAML file at the appropriate location for your platform:

code-templates-url: https://internal.example.com/akka-templates.json
context-url: https://internal.example.com/akka-context.zip
context-subdir: akka-context
additional-constitution-url: https://internal.example.com/akka-constitution.md
governance-policy-url: https://internal.example.com/akka-specify-governance/policy.yaml

To disable context downloading:

context-url: none

Any settings not specified in the configuration file will use their default values.

macOS MDM Configuration

For macOS devices managed via Mobile Device Management (MDM), you can deploy configuration using a property list (plist) file. This is the recommended approach for enterprise macOS deployments.

Create a configuration profile with the bundle identifier io.akka.cli containing the following keys:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>code-templates-url</key>
    <string>https://internal.example.com/akka-templates.json</string>
    <key>context-url</key>
    <string>https://internal.example.com/akka-context.zip</string>
    <key>context-subdir</key>
    <string>akka-context</string>
    <key>additional-constitution-url</key>
    <string>https://internal.example.com/akka-constitution.md</string>
    <key>governance-policy-url</key>
    <string>https://internal.example.com/akka-specify-governance/policy.yaml</string>
</dict>
</plist>

Deploy this as a managed preference using your MDM solution.

Precedence

Configuration is resolved in the following order (first match wins):

  1. macOS MDM plist (macOS only)

  2. System YAML configuration file

  3. Built-in defaults

Troubleshooting

If the YAML configuration file exists but contains invalid syntax, the CLI will print a warning to standard error and fall back to default values:

Warning: failed to parse /etc/akka/config.yml: yaml: unmarshal errors: ...

Verify your YAML syntax is correct if you see this warning.

Related documentation