How to get started with UpCloud Command-Line Interface

UpCloud Command-Line Interface, or UpCloud CLI for short, is a text-based user interface to UpCloud’s Infrastructure-as-a-service. It provides a fast command-line tool for accessing and managing your UpCloud resources.

UpCloud CLI allows you to manage your UpCloud resources from your local command line with simple and intuitive command structures, including Cloud Servers, storage, networking, Managed Databases, Managed Kubernetes and Managed Load Balancers. It’s offered as an addition to the current methods such as the UpCloud Control Panel and API for all users but especially developers and system administrators will likely find it highly useful!

In this guide, we’ll show you how to install the UpCloud CLI on your own computer and go over some of the basic functions.

Setting up API access

There are two methods to authenticate the CLI with the UpCloud API: using an API token (recommended) or using the username and password of a dedicated UpCloud subaccount.

If using the the subaccount we recomend creating a separate subaccount with only the necessary API permissions, rather than using the main account owner's credentials. See our getting started with UpCloud API using HTTP Basic authentication guide for step-by-step subaccount creation instructions.

Option 1: Using API tokens (Recommended)

API tokens are the recommended way to authenticate with the UpCloud API as they have configurable expiration dates, can be restricted to specific IP addresses, and can be easily revoked if compromised. For full details on creating and managing tokens, see our API Tokens guide.

Once you have created a token, you can store it in the upctl config file at $HOME/.config/upctl.yaml:

token: ucat_Your_API_Token

On Windows, the same file works as $HOME\.config\upctl.yaml in PowerShell.

Alternatively, your token can be stored in the UPCLOUD_TOKEN environment variable:

export UPCLOUD_TOKEN=ucat_Your_API_Token

On Windows, set the variable in PowerShell:

$env:UPCLOUD_TOKEN = "ucat_Your_API_Token"

The environment variable takes precedence over the config file if both are set.

Option 2: Using username and password

If you prefer to use the traditional authentication method, you can use a subaccount's username and password. See our getting started with UpCloud API using HTTP Basic authentication guide for instructions on creating a subaccount.

Once you have your subaccount credentials, store them in the upctl config file at $HOME/.config/upctl.yaml:

username: your_upcloud_username
password: your_upcloud_password

Alternatively, your credentials can also be stored in the environment variables UPCLOUD_USERNAME and UPCLOUD_PASSWORD. If the variables are set, matching config file items are ignored.

Installing the UpCloud CLI

Now that you’ve enabled API access to your UpCloud account, you can get started.

UpCloud CLI is available for macOS, Linux and Windows from the UpCloud CLI releases page on GitHub. The steps below cover the most common ways to install it. The UpCloud CLI documentation has instructions for other package managers, and for verifying the downloaded files.

In the commands below, replace <VERSION> with the version number of the latest release, for example 3.37.0.

macOS

On macOS, you can install the command-line interface using Brew. First, add the repository and then run the install command as shown below.

brew tap UpCloudLtd/tap
brew install upcloud-cli

If Brew refuses to load the formula from an untrusted tap, trust the tap and run the install command again:

brew trust upcloudltd/tap
brew install upcloud-cli

UpCloud CLI also supports shell completion. Run upctl completion bash --help for the setup commands, or replace bash with zsh, fish or powershell.

Linux

UpCloud CLI is available for a number of popular distributions e.g. Debian, Ubuntu and Arch Linux.

AUR

On Arch Linux, you can install the CLI with the following command.

yay -S upcloud-cli

Ubuntu and other Debian based distributions

Use the package corresponding to your Linux distribution, such as deb, rpm, or apk. For example, to install UpCloud CLI on Debian or Ubuntu, use the following commands.

curl -LO https://github.com/UpCloudLtd/upcloud-cli/releases/download/v<VERSION>/upcloud-cli_<VERSION>_amd64.deb
sudo apt install ./upcloud-cli_<VERSION>_amd64.deb

Other Linux distributions

If you can’t find a package applicable to your flavour of Linux, you can always use the precompiled version. Download it and extract the upctl binary to a directory in your PATH, for example, $HOME/.local/bin.

mkdir -p ~/.local/bin
curl -L -o upcloud-cli.tar.gz https://github.com/UpCloudLtd/upcloud-cli/releases/download/v<VERSION>/upcloud-cli_<VERSION>_linux_x86_64.tar.gz
tar -C ~/.local/bin -xzf upcloud-cli.tar.gz upctl

Bash completion can also be set up with an extra command. It needs the bash-completion package, which you can install with your package manager if it isn't installed already.

upctl completion bash | sudo tee /etc/bash_completion.d/upctl > /dev/null

Open a new shell for the completion to take effect.

Windows

Windows users can also make use of the UpCloud Command-Line Interface. No installer is needed: download the ZIP file, extract it, and add the folder to your PATH.

Run the following commands in PowerShell. They download the release, extract it to %LOCALAPPDATA%\upcloud-cli and add that folder to your user PATH. On a PC with an ARM processor, replace x86_64 with arm64.

Invoke-WebRequest -Uri "https://github.com/UpCloudLtd/upcloud-cli/releases/download/v<VERSION>/upcloud-cli_<VERSION>_windows_x86_64.zip" -OutFile "upcloud-cli.zip"
Expand-Archive -Path "upcloud-cli.zip" -DestinationPath "$env:LOCALAPPDATA\upcloud-cli"
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\upcloud-cli", "User")

The new PATH applies to new sessions. Open a new PowerShell window and check that the CLI runs:

upctl version

  Version:      3.37.0
  Build date:   2026-10-13T10:34:16Z
  Built with:   go1.25.7
  System:       windows
  Architecture: amd64

To set up tab completion for every new PowerShell session, add the completion script to your PowerShell profile:

if (-not (Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force }
Add-Content -Path $PROFILE -Value "upctl completion powershell | Out-String | Invoke-Expression"

Testing basic commands

Once you’ve enabled API access and installed the UpCloud CLI, you are ready to get cracking.

First, check the top-level command options. The help output is printed by default on most commands to make the CLI easy to explore and learn.

upctl --help

Usage:
upctl [command]

Available Commands:
account         Manage accounts
audit-log       Manage audit logs
completion      Generate the autocompletion script for the specified shell
database        Manage databases
file-storage    Manage file storage services
gateway         Manage gateways
help            Help about any command
host            Manage private cloud hosts
ip-address      Manage IP addresses
kubernetes      Manage Kubernetes clusters
load-balancer   Manage load balancers
network         Manage networks
network-peering Manage network peerings
object-storage  Manage managed object storage services
partner         Manage partner resources
router          Manage routers
server          Manage servers
server-group    Manage server groups
stack           Manage stacks (EXPERIMENTAL)
storage         Manage storages
version         Display software information
zone            Display zone information

If the CLI is working, test that it is able to access your UpCloud API credentials.

Account command lets you check the details of your UpCloud account.

upctl account show

  Username: exampleuser
  Credits:  100.00 EUR

  Resource Limits:
    Cores:                       250
    Detached Floating IPs:        10
    Load balancers:               50
    Managed object storages:      20
    Memory:                  1228800
    Network peerings:            100
    Networks:                    100
    NTP excess GiB:                0
    Public IPv4:                 100
    Public IPv6:                 100
    Storage HDD:               61440
    Storage MaxIOPS:           20480
    Storage SSD:               10240
    GPUs:                          3

Server command is a top-level command that you will likely be using a fair bit. Run the following command to list all Cloud Servers your API account has permission to.

upctl server list

 UUID                                   Hostname   Plan                Zone      State
────────────────────────────────────── ────────── ─────────────────── ───────── ─────────
 00229ddf-0e46-45b5-a8f7-cad2c8d11f6a   server1    PREMIUM-2xCPU-4GB   de-fra1   stopped
 003c9d77-0237-4ee7-b3a1-306efba456dc   server2    PREMIUM-1xCPU-2GB   sg-sin1   started

Storage command can be used to manage both your own cloud storage devices as well as explore the public templates. The next command will list all public templates.

upctl storage list --public

The command outputs can also be piped to other command-line tools. For example, use grep to narrow down the list of templates to find a specific public template.

upctl storage list --public | grep Debian

 01000000-0000-4000-8000-000020080101   Debian GNU/Linux 13.1.0 (Trixie) Installation CD            no          cdrom         1   online                 public
 01000000-0000-4000-8000-000020070101   Debian GNU/Linux 12.12.0 (Bookworm) Installation CD         no          cdrom         1   online                 public
 01000000-0000-4000-8000-000020080100   Debian GNU/Linux 13 (Trixie)                                no          template     10   online                 public
 01000000-0000-4000-8000-000020070100   Debian GNU/Linux 12 (Bookworm)                              no          template     10   online                 public
 01000000-0000-4000-8000-000020060100   Debian GNU/Linux 11 (Bullseye)                              no          template      3   online                 public
 01000000-0000-4000-8000-000020060101   Debian GNU/Linux 11.0.0 (Bullseye) Installation CD          no          cdrom         1   online                 public
 01000000-0000-4000-8000-000020050102   Debian GNU/Linux 10.0.0 (Buster) Installation CD            no          cdrom         1   online                 public

Other commands include options for managing your networking such as static and floating IP addresses, SDN Private networks and SDN Routers. We’ll go more into detail on this further ahead in this guide.

Cloud Servers

One of the main benefits of the UpCloud CLI is the speed and ease of managing your cloud services. For example, deploying a new Cloud Server takes but a single command.

The example below deploys a new Cloud Server on the Premium plan with 2 CPU cores and 4 GB of memory, running Debian 13. It also secures the server right from deployment with your SSH key, so no password is created.

upctl server create \
  --zone de-fra1 \
  --plan PREMIUM-2xCPU-4GB \
  --os "Debian GNU/Linux 13 (Trixie)" \
  --ssh-keys ~/.ssh/id_ed25519.pub \
  --hostname example.com \
  --title "Example server"

You can find the full detailed list of the configuration parameters using the command below.

upctl server create --help

Once deployed, check the status of the new server.

Notice how using the UpCloud CLI, you do not need to remember UUIDs. Rather most resources can be addressed by their name as in the example command below.

upctl server show example.com

  Common
    UUID:          000eb0de-a2af-4d34-8e64-dbfcca60656b
    Hostname:      example.com
    Title:         Example server
    Plan:          PREMIUM-2xCPU-4GB
    Zone:          de-fra1
    State:         started
...

The example output above shows the first few lines of details about the Cloud Server.

If you want to make changes to your Cloud Server, e.g. change the hostname or description, enable Firewall or Metadata, many of the changes can be done without shutting down the server.

upctl server modify example.com --enable-metadata

To change the server plan, shut down the server first. The --wait option returns once the server has stopped. Moving to a larger plan is also possible while the server is running, see How to scale Cloud Servers with hot resize.

upctl server stop example.com --wait

Afterwards, you can make changes to the server configuration.

upctl server modify example.com --plan PREMIUM-4xCPU-8GB

Then start up the server again.

upctl server start example.com

That’s it! Your Cloud Server should then start up momentarily with the additional resources available right away.

Storage devices

All Cloud Servers deployed using Premium plans offer ample storage out of the gate but sometimes you just need more capacity. Luckily, UpCloud CLI offers quick and easy commands for creating additional storage devices and attaching them to your Cloud Server.

Furthermore, most storage operations can even be done without shutting down the server!

Create new storage devices by defining the type, size, and location, as well as naming the storage. For example, let’s create a secondary MaxIOPS storage for our example.com Cloud Server.

upctl storage create \
  --title example.com-storage1 \
  --size 50 \
  --zone de-fra1 \
  --tier maxiops

Once created, you can query the storage devices for details using the command below.

upctl storage show example.com-storage1

Attaching storage devices to a server is as easy as creating them. You can identify the storage device by its title or UUID.

upctl server storage attach example.com --storage example.com-storage1

Then check the server details again to see that the new storage device was attached successfully.

upctl server show example.com

...
  Storage: (Flags: B = bootdisk, P = part of plan)

     UUID                                   Title                  Type   Address    Size (GiB)   Encrypted   Flags
    ────────────────────────────────────── ────────────────────── ────── ────────── ──────────── ─────────── ───────
     01b8846a-0e12-4163-b55c-b580e4e0f53e   example.com-OS         disk   virtio:0           50   no
     012f100e-1af6-4b9a-878d-7ca6f019dc0b   example.com-storage1   disk   virtio:1           50   no          P
...

Quick and easy! However, after attaching new storage devices, it’s still necessary to finish the process at the operating system level. You can find out more about formatting the storage device in our guide on adding storage devices.

Networks and IP addresses

Networking is also an important part of any cloud infrastructure and naturally, you can manage yours via the UpCloud CLI.

Creating SDN Private networks is a great way for securely connecting Cloud Servers. Let’s test out the command-line interface by setting up a new SDN Private network for our example.com Cloud Server.

upctl network create --name sdn.example --zone de-fra1 --ip-network 'address=192.168.10.0/24,dhcp=true'

When done, check that the network you created was added to the list.

upctl network list

 UUID                                   Name            Router                                 Type      Zone
────────────────────────────────────── ─────────────── ────────────────────────────────────── ───────── ─────────
 03476522-0a9a-4924-a567-d8206f2d266d   sdn.example                                            private   de-fra1

Now that we have our network ready, let’s attach our Cloud Server to it.

First, however, we’ll need to shut down the server.

upctl server stop example.com --wait

Create a new network interface and attach SDN Private network to it with the command below. You can refer to the network by its name or UUID.

upctl server network-interface create example.com --network sdn.example

Afterwards, start up the server again.

upctl server start example.com

Besides networks, UpCloud CLI also allows you to manage your individual IP addresses.

Create a new floating IP address with the example command below.

upctl ip-address assign --floating --zone de-fra1

Once created, the new floating IP will show up on the list of IP addresses. The command below will show all IP addresses reserved to your UpCloud account.

upctl ip-address list

 Address                                  Access    Family   Part of Plan   PTR Record                                    Server                                 Floating   Zone
──────────────────────────────────────── ───────── ──────── ────────────── ───────────────────────────────────────────── ────────────────────────────────────── ────────── ─────────
 2a04:3542:1000:910:1444:a3ff:fe20:13dd   public    IPv6     no             1444-a3ff-fe20-13dd.v6.de-fra1.upcloud.host   000eb0de-a2af-4d34-8e64-dbfcca60656b   no         de-fra1
 10.4.37.8                                utility   IPv4     no                                                           000eb0de-a2af-4d34-8e64-dbfcca60656b   no         de-fra1
 85.9.206.187                             public    IPv4     no             85-9-206-187.de-fra1.upcloud.host                                                    yes        de-fra1
 94.237.85.16                             public    IPv4     yes            94-237-85-16.de-fra1.upcloud.host             000eb0de-a2af-4d34-8e64-dbfcca60656b   no         de-fra1

Attach the floating IP address to the example.com server with the next command. For this, you will need the MAC address of one of the public network interfaces on your Cloud Server. Commonly this should be the first public IP address on your Cloud Server. Check the output from upctl server show example.com to find the right one.

upctl ip-address modify 85.9.206.187 --mac 16:44:a3:20:52:5d

When attached, the floating IP address will show up to your Cloud Server. However, to enable network traffic through the floating IP, you would still need to configure it on the operating system level. Check out our other guides on OS-specific instructions for attaching floating IP addresses.

Conclusions

Congratulations! By following along and completing the steps explained in this guide, you should now have a pretty good grasp of the UpCloud Command-Line Interface. It really makes it quick work managing your cloud infrastructure!

Additionally, using the UpCloud CLI, you could easily script and automate common tasks to further speed up your workflow. You might be surprised at how much can be accomplished with a few simple lines of clever commands.