Skip to content

Getting started

upctl provides a command-line interface to UpCloud services. It allows you to control your resources from the command line or any compatible interface.

Install upctl

upctl can be installed from a pre-built package in the repositories GitHub releases using a package manager or from sources with go install:

Download pre-built package from GitHub releases and install it with your package manager.

On Ubuntu or Debian, use the .deb package.

curl -Lo upcloud-cli_None_amd64.deb https://github.com/UpCloudLtd/upcloud-cli/releases/download/vNone/upcloud-cli_None_amd64.deb
sudo apt install ./upcloud-cli_None_amd64.deb

On RHEL based distributions, use the .rpm package.

curl -Lo upcloud-cli-None-1.x86_64.rpm https://github.com/UpCloudLtd/upcloud-cli/releases/download/vNone/upcloud-cli-None-1.x86_64.rpm
sudo dnf install ./upcloud-cli-None-1.x86_64.rpm

Use homebrew to install upctl from UpCloudLtd tap.

brew tap UpCloudLtd/tap
brew install upcloud-cli

First, download the archived binary from GitHub releases to current folder and extract the binary from the archive.

Invoke-WebRequest -Uri "https://github.com/UpCloudLtd/upcloud-cli/releases/download/vNone/upcloud-cli_None_windows_x86_64.zip" -OutFile "upcloud-cli_None_windows_x86_64.zip"
Expand-Archive -Path "upcloud-cli_None_windows_x86_64.zip"

# Print current location
Get-Location

Then, close the current PowerShell session and open a new session as an administrator. Move the binary to upcloud-cli folder in Program Files, add the upcloud-cli folder in Program Files to Path.

# Open the PowerShell with Run as Administrator option.
# Use Set-Location to change into folder that you used in previous step.

New-Item -ItemType Directory $env:ProgramFiles\upcloud-cli\ -Force
Move-Item -Path upcloud-cli_None_windows_x86_64\upctl.exe -Destination $env:ProgramFiles\upcloud-cli\ -Force

# Setting the Path is required only on first install.
# Thus, this step can be skipped when updating to a more recent version.
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", [EnvironmentVariableTarget]::Machine) + ";$env:ProgramFiles\upcloud-cli\", [EnvironmentVariableTarget]::Machine)

After running the above commands, close the administrator PowerShell session and open a new PowerShell session to verify installation succeeded.

Install the latest version of upctl with go install, by running:

go install github.com/UpCloudLtd/upcloud-cli/v3/...@latest

Pull the latest build from GHCR by running:

docker pull ghcr.io/upcloudltd/upctl:latest

After installing upctl, you can run upctl version command to verify that the tool was installed successfully.

upctl version

Configure shell completions

upctl provides shell completions for multiple shells. Run upctl completion --help to list the supported shells.

upctl completion --help

To configure the shell completions, follow the instructions provided in the help output of the command matching the shell you are using. For example, if you are using zsh, run upctl completion zsh --help to print the configuration instructions.

Bash completions

On bash, the completions depend on bash-completion package. Install and configure the package according to your OS:

First, install bash-completion package, if it has not been installed already, and add command to source the completions to your .bashrc.

On Ubuntu or Debian, use apt command to install the package:

sudo apt install bash-completion
echo "[ -f /etc/bash_completion ] && . /etc/bash_completion" >> ~/.bashrc

On RHEL based distributions, use dnf command to install the package.

sudo dnf install bash-completion
echo "[ -f /etc/bash_completion ] && . /etc/bash_completion" >> ~/.bashrc

Finally, configure the shell completions for upctl by either sourcing upctl completion bash output in your bash .bashrc or by saving the output of that command in upctl file under /etc/bash_completion.d/:

# First alternative
echo 'source <(upctl completion bash)' >>~/.bashrc

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

# Source completions to current shell session
. /etc/bash_completion

First, install bash-completion package, if it has not been installed already, and add command to source the completions to your .bash_profile.

brew install bash-completion
echo '[ -f "$(brew --prefix)/etc/bash_completion" ] && . "$(brew --prefix)/etc/bash_completion"' >> ~/.bash_profile

Then configure the shell completions for upctl by saving the output of upctl completion bash in upctl file under /etc/bash_completion.d/:

upctl completion bash > $(brew --prefix)/etc/bash_completion.d/upctl
. $(brew --prefix)/etc/bash_completion

Configure credentials

To be able to manage your UpCloud resources, you need to configure credentials for upctl and enable API access for these credentials.

Define the credentials by setting UPCLOUD_USERNAME and UPCLOUD_PASSWORD environment variables.

API access can be configured in the UpCloud Hub on Account page for the main-account and on the Permissions tab of the People page for sub-accounts. We recommend you to set up a sub-account specifically for the API usage with its own username and password, as it allows you to assign specific permissions for increased security.

Execute commands

To verify you are able to access the UpCloud API, you can, for example, run upctl account show command to print your current balance and resource limits.

upctl account show

For usage examples, see the Examples section of the documentation.

For reference on how to use each sub-command, see the Commands reference section of the documentation. The same information is also available in --help output of each command.