Using the CLI

Many of the operations you can perform with Akka Serverless can be done via the akkasls CLI instead of the web-based graphical user-interface.

Generally, akkasls is followed by a command, possibly followed by sub-commands and parameters. You may also optionally supply flags, preceded by -- (two hypens) that modify the operation of the command-line client itself. You will not often need to use flags. The flags are described below the list of commands.

Using akkasls commands

The following sub-sections list each of the available commands, and their sub-commands, if applicable, that can be issued via the command-line client.


The akkasls help command provides help for any command and subcommand. Just append the command path. Alternatively, one can specify the -h or --help flag. Some examples:

  • akkasls help auth

  • akkasls help config use-context

  • akkasls project list -h


The akkasls auth command allows you to authorize your command-line client against your account on Akka Serverless. This allows the command-line client to do all the operations you are allowed, just as if you did these operations in the Web GUI.

Auth login

Typing akkasls auth login will (normally) launch your web browser and take you to the proper URL to enter your credentials. The command-line client will print "Waiting for UI login…​" and pause while this happens, and then resume with a message once it receives the authorization token from the Akka Serverless server.

If successfully authenticated, and if you already have a project, the current project will be set to the active one.

Auth logout

The command akkasls auth logout does the opposite of the [auth login] command. Your authorization token is removed, your akkasls context is deleted and reset to default.

Auth current login information

The command akkasls auth current-login shows details for the currently logged in user. This includes name, email, and whether the user has been verified.

Auth list tokens

The command akkasls auth tokens list will display all currently authorized tokens for your account.

Auth tokens revoke

The command akkasls auth tokens revoke tokenid allows you to make a specific authorization token invalid, that is, to log out whatever that token was allowing.

The token ID can be seen in the auth tokens list.


You can, optionally, provide the -no-launch-browser flag with the akkasls auth command (e.g. akkasls -no-launch-browser auth), in which case the command-line client will simply display the URL you should go to in order to do the authorization, rather than try to launch the browser itself. You can use this if, for some reason, the command-line client is unable to launch your browser for you.

If for some reason the command-line client cannot launch a browser (when -no-launch-browser is not supplied), it will use this behaviour itself, with an explanatory message saying that it could not launch the browser.


The project commands manipulate the projects in your Akka Serverless account, where a project is a collection of services.

New project

The akkasls project new FRIENDLY-NAME [DESCRIPTION] command will create a new project in your Akka Serverless account, giving it the friendly name FRIENDLY-NAME and the description [DESCRIPTION].

Project friendly names should describe the project so that you and other project members can identify it and its purpose.

Project friendly names must conform to the following:

  • Up to 63 characters

  • Can include:

    • lowercase letters

    • numbers

    • hyphens (-)

  • Must not:

    • start or end with hyphens (-)

  • Cannot include:

    • underscores (_)

    • spaces

    • non-alphanumeric characters

If the [DESCRIPTION] includes spaces or other special characters, it must be surrounded by quotes.

Get project

The akkasls project get id command will display information about the project with the id id, if it exists.

List projects

The akkasls project list command will list a quick one-line summary of all projects that your Akka Serverless account has access to. The current project will have an asterisk '*' next to it.

You can change the current project using Set config value.

Set/unset project resources

The akkasls project set resource command will set the value for a particular project resource. The akkasls project unset resource command will do the opposite.

At this time, the only settable resource is log-aggregator. The behavior for this is modified using command line flags, in particular:

  • --google-key string

    • The google key file. Either this or --google-key-file is required if stackdriver is the log service.

  • --google-key-file string

    • The google key file. Either this or --google-key is required if stackdriver is the log service.

  • --log-service string

    • The type of the log service, one of: [stackdriver]


The service command lists the services in a project.

You need to set the current project before running the service command. You can set the current project using Set config value.

List services

The akkasls service list command will list a one-line summary of all services under the current project.


The role commands (which can also be invoked as roles) allow you to associate user roles (authorizations) with the current project.

List roles

The command akkasls role list will display a list of possible roles for the current project. You establish the "current project" by using either akkasls config set project my-project or specifying the --project=my_project flag.

List role bindings

The command akkasls role list-bindings will display the bindings of each role in the project to each user with access to this project - that is, which user can fulfill which role(s).

Add role binding

The command akkasls role add-binding user role will associate the user user with the role specified as role, adding a new binding.

Delete role binding

The command akkasls role delete-binding user role will remove the association between the user user and the named role, effectively removing this user from that role.

Manage invitations

The command akkasls role invitation subcommand is used to manage invitations to user roles on a project. Aliases for this command are invitations, invite, invitation, invites. The available subcommands are:

  • delete

  • Delete an invitation from a project

  • invite-user

  • Invite a user to a project

  • list

  • List invitations to a project


The config command is used to display and set configuration contexts and values that apply to subsequent commands. Configuration settings are stored in a file on your local system, by default at .cloudstatemachine/config.yaml in your home directory. This can be adjusted with the --config flag, described later.

Show current config context

The command akkasls config current-context will display the name of your currently selected configuration context. A configuration context represents a set of configuration values intended to be used together - you may have several contexts, and switch between them easily with this command (or flags, as described later).

List contexts

The command akkasls config list-contexts will List all of the configured contexts.

Use config context

The command akkasls config use-context context-name will switch the currently selected configuration context to the context specified with context-name.

This context will remain selected for subsequent commands.

Note: You can also use the --context flag to specify a different context for an individual command.

Set config value

The command akkasls config set key value will write the specified value as the current value for the key key in the current config context. The same key in other config contexts will not be affected.

A common use of this command is to establish a specific project as the "current project" by using akkasls config set project my-project.

Get config value

The command akkasls config get key will display the current value of the specified key in the current configuration context.

List config values

The command akkasls config list will display all configuration keys and their corresponding values in the current configuraiton context.

Delete context

The command akkasls config delete-context context will delete the given context.

Rename context

The command akkasls config rename-context newname will rename the current context to the given name.


The family of akkasls docker commands are used to manage docker credentials so that services can pull images from credentialed docker repositories.

Add credentials

Use the akkasls docker add-credentials [flags] command to add a set of docker credentials to the project. The flags are:

  • --docker-email string

  • The docker email address

  • --docker-password string

  • The docker password

  • --docker-server string

  • The docker server, for example

  • --docker-username string

  • The docker username

Delete credentials

The command docker delete-credentials id is used to remove a set of docker credentials from the project. Use the List credentials command to find the id.

List credentials

The command docker list-credentials lists all the docker credentials set for the project. (The password is not displayed.) Use the id if deleting credentials with the Delete credentials command.

Service descriptors

The command descriptor get service-name shows the top-level protobuf descriptor for the service with name service-name.

For example:

$ akkasls descriptor get shopping-cart
service ShoppingCart {
  rpc AddItem ( .com.example.shoppingcart.AddLineItem ) returns ( .google.protobuf.Empty ) {
    option (.cloudstate.eventing) = { in:"items" };
    option (.google.api.http) = { post:"/cart/{user_id}/items/add" body:"*" };
  rpc GetCart ( .com.example.shoppingcart.GetShoppingCart ) returns ( .com.example.shoppingcart.Cart ) {
    option (.google.api.http) = { get:"/carts/{user_id}" additional_bindings:<get:"/carts/{user_id}/items" response_body:"items"> };
  rpc RemoveItem ( .com.example.shoppingcart.RemoveLineItem ) returns ( .google.protobuf.Empty ) {
    option (.google.api.http) = { post:"/cart/{user_id}/items/{product_id}/remove" };

Bash Completion

Completion allows you to hit [TAB] on a partially entered akkasls command and have the shell complete the command, subcommand or flag for you. To load completion for bash run

. <(akkasls completion)

To configure your bash shell to load completions for each session add this to your .bashrc or .profile file:

# ~/.bashrc or ~/.profile
. <(akkasls completion)

In order use bash completion, you may need to enable it in your .bashrc (or appropriate) file with something like:

if [ -f /etc/bash_completion ]; then
 . /etc/bash_completion


The command akkasls version prints the version number of akkasls.

Using akkasls Flags

Any akkasls command can be preceded by one or more flags that modify the operation of the command, as follows:


The --timeout=nnn flag allows you to adjust the amount of time the command-line client will wait for a response from the Lightbend Cloudstate server. If for some reason your connection is especially slow, you can specify a number of seconds that the current command will wait for a response before timing out.


The --config=xxx flag allows you to specify an alternative (full-path) location for your local configuration file, which controls the operation of your command-line client.

Normally, you would use the default location (.cloudstatemachine/config.yaml in your home directory)


The flag --output=format, where 'format' is one of the options of text, json or gotemplate-xxx can be used to change the format of the output of any command.

The default is text.

This flag may be abbreviated -o.


The flag --context=xxx allows you to specify an alternative configuration context (where xxx is the context you prefer).

This uses the specified context only for the current command, after which the current context returns to whatever it was before this command. See config use-context to switch the context for all subsequent commands.

Deploy a statefulService

See Deploying Akka Serverless Services for instructions on how to deploy services.