# Command Line Interface `exo` is the [official command-line tool][exo] 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. ```bash 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. ```bash 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](https://github.com/exoscale/cli/releases). - 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](https://hub.docker.com/r/exoscale/cli) with the following command: ```bash docker run -it exoscale/cli ``` > [!NOTE] > The docker builds are for AMD64 architecture only. For ARM or ARM64, use the tar.gz release. ### Apple macOS Install with [Homebrew](https://brew.sh/): ```bash 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](https://scoop.sh) before installing `exo` with: ```bash scoop bucket add exoscale-cli https://github.com/exoscale/cli scoop install exoscale-cli ``` To update `exo` to the latest version: ```bash 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 ```bash 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. ```bash 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](https://portal.exoscale.com/iam/api-keys). See the [IAM section]({{< ref "/product/security/iam/quick-start" >}}) of this documentation. ### Configuration The CLI will guide you in the initial configuration: ```bash 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: ```bash 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: ```bash exo compute instance create example ``` Output: ```bash ✔ 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]({{< ref "/product/networking/security-group" >}}) 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 ` option. ### Create a firewall rule to allow SSH connection By default, [security groups]({{< ref "/product/networking/security-group" >}}) 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: ```bash exo compute security-group rule add default --network 0.0.0.0/0 --port 22 ``` Output: ```bash ✔ 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. ```bash exo compute instance ssh example ``` Output: ```bash 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. ```bash exo compute instance delete example ``` Output: ```bash [+] 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](https://pkg.go.dev/text/template) might be more suitable for non-interactive uses: ```bash # 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. [exo]: https://github.com/exoscale/cli