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, Docker image, 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_3.14.0_amd64.deb https://github.com/UpCloudLtd/upcloud-cli/releases/download/v3.14.0/upcloud-cli_3.14.0_amd64.deb
sudo apt install ./upcloud-cli_3.14.0_amd64.deb
On RHEL based distributions, use the .rpm package.
Use homebrew to install upctl from UpCloudLtd tap.
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/v3.14.0/upcloud-cli_3.14.0_windows_x86_64.zip" -OutFile "upcloud-cli_3.14.0_windows_x86_64.zip"
Expand-Archive -Path "upcloud-cli_3.14.0_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_3.14.0_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:
Install with mise:
```sh mise use upctl # or with -g for global ´´´
Install with aqua, aqua.yaml example:
```yaml registries: - type: standard packages: - name: UpCloudLtd/upcloud-cli@v3.14.0 ´´´
After installing upctl, you can run upctl version command to verify that the tool was installed successfully.
Configure shell completions
upctl provides shell completions for multiple shells. Run upctl completion --help to list the supported shells.
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.
On Ubuntu or Debian, use apt command to install the package:
On RHEL and Fedora based distributions, use dnf command to install the package.
Most distributions' packages enable bash-completion automatically. If not, something like this can be done to accomplish that:
printf "%s\n" "[[ -f /usr/share/bash-completion/bash-completion ]] && . /usr/share/bash-completion/bash-completion" >> ~/.bashrc
If your bash-completion version is 2.12 or newer, no further steps are needed, upctl completion will load automatically on demand. With older bash-completion versions, the autoloading needs to be set up. Something like this will accomplish that:
# Either system wide:
printf "%s\n" 'eval -- "$("$1" completion bash 2>/dev/null)"' > /usr/share/bash-completion/completions/upctl
# ...or per user:
mkdir -p ~/.local/share/bash-completion/completions
printf "%s\n" 'eval -- "$("$1" completion bash 2>/dev/null)"' > ~/.local/share/bash-completion/completions/upctl
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/:
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.
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.