exo is the official command-line tool to access Exoscale services. You can manage your infrastructure from a user-friendly command line, with all the benefits of a scriptable interface.

Installation

GNU/Linux

Debian and Red Hat based distributions

On Debian and Red Hat based distributions like Ubuntu or Fedora, we recommend using the installation script.

curl -fsSL https://raw.githubusercontent.com/exoscale/cli/master/install-latest.sh | sh

exo is now installed and you will be able to update to future versions through your package manager or by simply running the script again.

Arch Linux

We provide several exo packages on the AUR that you can install with the following procedure.

gpg --keyserver keys.openpgp.org --recv-key 7100E8BFD6199CE0374CB7F003686F8CDE378D41
git clone https://aur.archlinux.org/exoscale-cli-bin.git
cd exoscale-cli-bin/
makepkg --install

Alternatively there are two packages building from source https://aur.archlinux.org/exoscale-cli.git and https://aur.archlinux.org/exoscale-cli-git.git where the latter builds from the latest commit on the master branch and the former from the latest release commit.

Other distributions

Download the archive corresponding to your operating system from the latest release on GitHub.

  • Download cli_$VERSION_linux_amd64.tar.gz
  • Expand it
  • Put the exo binary into your $PATH, e.g. /usr/local/bin/

Docker

You can run the CLI as a Docker container with the following command:

docker run -it exoscale/cli <command argument>

Note

The docker builds are for AMD64 architecture only. For ARM or ARM64, use the tar.gz release.

Apple macOS

Install with Homebrew:

brew tap exoscale/tap
brew install exoscale-cli

Or alternatively:

  • Download and open cli_$VERSION_darwin_amd64.tar.gz
  • Copy the exo executable in a directory inside your $PATH

Microsoft Windows

The exo cli works for both the traditional Command Prompt as well as the more modern PowerShell.

We recommend installing it through the scoop package manager as it can also update the application for you.

If you haven’t installed scoop already, follow the instructions at scoop.sh before installing exo with:

scoop bucket add exoscale-cli https://github.com/exoscale/cli
scoop install exoscale-cli

To update exo to the latest version:

scoop update
scoop update exoscale-cli

If you still prefer installing manually: - Download cli_%VERSION%_windows_amd64.zip - Open the command line shell (cmd.exe) and type the following commands

    mkdir C:\exoscale
    setx path "%path%;C:\exoscale;"
  • Put all files from zip archive into C:\exoscale\

Using pre-built releases

You can find pre-built releases of the CLI [here][https://github.com/exoscale/cli/releases].

From sources

To build exo from sources, a Go compiler >= 1.16 is required.

$ git clone https://github.com/exoscale/cli
$ cd cli
$ make build

Upon successful compilation, the resulting exo binary is stored in the bin/ directory.

Configuration

A configuration file holding your credentials is required. You can generate one via a guided prompt. The following parameters are requested:

  • API Key
  • Secret Key

If you do not already have a key and the corresponding secret, you can generate one using the Exoscale Portal. See the IAM section of this documentation.

Configuration

The CLI will guide you in the initial configuration:

$ exo config

After you save, you can review your current configuration later by running the exo config show command.

Commands overview

You are now ready to use the CLI. To explore the possibilities of the CLI, use the raw exo --help command to list commands and options:

$ exo --help

Create a Compute instance

The exo compute instance command allows you to do basic CRUD operations on Compute instances.

Run exo compute instance create to deploy an instance:

$ exo compute instance create example
 ✔ Creating instance "example"... 18s
┼──────────────────────┼──────────────────────────────────────┼
│   COMPUTE INSTANCE   │                                      │
┼──────────────────────┼──────────────────────────────────────┼
│ ID                   │ 7b014127-e635-4d14-b8c4-090549891583 │
│ Name                 │ example                              │
│ Creation Date        │ 2021-09-15 15:45:28 +0000 UTC        │
│ Instance Type        │ standard.medium                      │
│ Template             │ Linux Ubuntu 20.04 LTS 64-bit        │
│ Zone                 │ ch-gva-2                             │
│ Anti-Affinity Groups │ n/a                                  │
│ Security Groups      │ default                              │
│ Private Networks     │ n/a                                  │
│ Elastic IPs          │ n/a                                  │
│ IP Address           │ 85.217.161.93                        │
│ IPv6 Address         │ -                                    │
│ SSH Key              │ -                                    │
│ Disk Size            │ 50 GiB                               │
│ State                │ running                              │
│ Labels               │ n/a                                  │
┼──────────────────────┼──────────────────────────────────────┼

The command automatically creates an SSH key specifically for this instance. If you need to use an SSH key of your own, you can refer to it by name with the --ssh-key <keyname> option.

Create a firewall rule to allow SSH connection

By default, security groups without any rule specified block all incoming connections. To reach your instance via SSH, you need to explicitly allow ingress on port 22.

Use the exo compute security-group rule add command:

$ exo compute security-group rule add default --network 0.0.0.0/0 --port 22
 ✔ Adding rule to Security Group "default"... 3s
┼──────────────────┼────────────────────────────────────────────────────────────────────┼
│  SECURITY GROUP  │                                                                    │
┼──────────────────┼────────────────────────────────────────────────────────────────────┼
│ ID               │ 9eb186db-cf1f-4f8a-8218-03d2a0150f11                               │
│ Name             │ default                                                            │
│ Description      │                                                                    │
│ Ingress Rules    │                                                                    │
│                  │   dfc6d3a6-a15f-430f-b999-82a80ffc3aac      TCP   0.0.0.0/0   22   │
│                  │                                                                    │
│ Egress Rules     │ -                                                                  │
│ External Sources │ -                                                                  │
┼──────────────────┼────────────────────────────────────────────────────────────────────┼

Connect to a Compute instance via SSH

The exo compute instance ssh command lets you directly log into an instance using an SSH connection.

$ exo compute instance ssh example
Host key fingerprint is SHA256:nmAfu17qHLkJkEpOy2qXWaV5nSMq0yzKD6j0giZIghk
Welcome to Ubuntu 19.04 LTS (GNU/Linux 4.15.0-20-generic x86_64)

ubuntu@example:~$

Cleaning up

Removing an instance is as simple as creating one, but beware - there is no way to undo a deletion.

$ exo compute instance delete example
[+] Are you sure you want to delete instance "example"? [yN]: y
 ✔ Deleting instance "example"... 6s

Alternative output formats

By default, commands outputting information as a result of an operation will format the content in a table, so it is easier to read.

If you use the exo CLI in scripts, output formats JSON or templated text might be more suitable for non-interactive uses:

# JSON
$ exo compute instance show example -O json | jq -r .ip_address
85.217.161.93

# Text templating
$ exo compute instance show example -O text --output-template '{{.ID}}@{{.Zone}}'
7b014127-e635-4d14-b8c4-090549891583@ch-gva-2

You can find more information with the exo help output command in the CLI.