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.
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/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:
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, 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, 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.