upcloud-cli

UpCloud CLI - upctl

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

UpCloud command-line interface

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

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 on the Account page of the UpCloud Hub. 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.

Usage:
upctl [command]

Available Commands:
account      Manage accounts
completion   Generate the autocompletion script for the specified shell
database     Manage databases
help         Help about any command
ip-address   Manage IP addresses
kubernetes   Manage Kubernetes clusters (EXPERIMENTAL)
loadbalancer Manage load balancers
network      Manage networks
router       Manage routers
server       Manage servers
storage      Manage storages
version      Display software information
zone         Display zone information

Options:
  -t, --client-timeout duration   Client timeout to use in API calls.
                                  Default: 0s

  --config string                 Configuration file path.

  --debug bool                    Print out more verbose debug logs.
                                  Default: false

  --force-colours                 Force coloured output despite detected terminal support.

  --no-colours                    Disable coloured output despite detected terminal support. Colours can also be disabled by setting
                                  NO_COLOR environment variable.

  -o, --output string             Output format (supported: json, yaml and human)
                                  Default: human

Use "upctl [command] --help" for more information about a command.

Installation

Install the latest with Go by running:

go install github.com/UpCloudLtd/upcloud-cli/cmd/upctl/v2@latest

To use upctl as a binary, download it from the Releases page. After downloading, verify that the client works.

macOS

brew tap UpCloudLtd/tap
brew install upcloud-cli
upctl -h

Setting up bash completion requires a few commands more.

First, install bash-completion, if it is not installed already.

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

Linux

AUR

yay -S upcloud-cli

Other Linux distros

Use the package corresponding to your distro (deb, rpm, apk) from the releases page, example for Debian like:

# Replace <VERSION> with the version you want to install
curl -Lo upcloud-cli.deb https://github.com/UpCloudLtd/upcloud-cli/releases/download/v<VERSION>/upcloud-cli-<VERSION>_amd64.deb
sudo dpkg -i upcloud-cli.deb
upctl -h

Bash completion can also be set up with some extra commands. You should adapt this for your package manager.

First, install bash-completion, if it is not installed already.

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

Then 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
. /etc/bash_completion

Windows

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 -Destination 'C:\Program Files\Upcloud CLI'
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Program Files\Upcloud CLI", [System.EnvironmentVariableTarget]::Machine)
upctl.exe -h

Quick Start

Create a upctl.yaml config file with user credentials into your home directory's .config dir ($HOME/.config/upctl.yaml).

username: your_upcloud_username
password: your_upcloud_password

Credentials can also be stored at environment variables UPCLOUD_USERNAME and UPCLOUD_PASSWORD. If variables are set, matching config file items are ignored.

NOTE: Make sure your account allows API connections. To do so, log into UpCloud control panel and go to Account -> Permissions -> Allow API connections checkbox.

Run something to test that the credentials are working.

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

Exit codes

Exit code communicates success or the type and number of failures. Possible exit codes of upctl are:

Examples

Every command has a help and examples included and you can find all its options by adding -h at the end of the command, like upctl network list -h. Below, you'll find a few common commands that have many other available options as well.

• Create a new server

upctl server create --hostname test-server.io --zone de-fra1 --ssh-keys ~/.ssh/id_rsa.pub

• Create storage

upctl storage create --size 25 --title test-storage --zone es-mad1

Note: Storage size is in GB.

• Attach storage to server

upctl server storage attach <SERVER-UUID> --storage <STORAGE-UUID>

Documentation

The detailed documentation is available in GitHub pages.

To generate markdown version of command reference, run make md-docs. Command reference will then be generated into docs/commands_reference.

make md-docs

To run the MkDocs documentation locally, run make docs and start static http server (e.g., python3 -m http.server 8000) in site/ directory or run mkdocs serve in repository root.

make docs
mkdocs serve

Contributing

Contributions from the community are much appreciated! Please note that all features using our API should be implemented with UpCloud Go API SDK. If something is missing from there, add an issue or PR in that repository instead before implementing it here.

• Check GitHub issues and pull requests before creating new ones
  • If the issue isn't yet reported, you can create a new issue.
• Besides bug reports, all improvement ideas and feature requests are more than welcome and can be submitted through GitHub issues.
  • New features and enhancements can be submitted by first forking the repository and then sending your changes back as a pull request.
• Following semantic versioning, we won't accept breaking changes within the major version (1.x.x, 2.x.x etc).
  • Such PRs can be open for some time and are only accepted when the next major version is being created.

Development

• upctl uses UpCloud Go API SDK
• upctl is built on Cobra

You need a Go version 1.18+ installed on your development machine. Use make to build and test the CLI. Makefile help can be found:

$ make help
build                Build program binary for current os/arch
doc                  Generate documentation (markdown)
build-all            Build all targets
build-linux          Build program binary for linux x86_64
build-darwin         Build program binary for darwin x86_64
build-windows        Build program binary for windows x86_64
build-freebsd        Build program binary for freebsd x86_64
test                 Run tests
fmt                  Run gofmt on all source files
clean                Cleanup everything

Debugging

Environment variables UPCLOUD_DEBUG_API_BASE_URL and UPCLOUD_DEBUG_SKIP_CERTIFICATE_VERIFY can be used for HTTP client debugging purposes. More information can be found in the client's README file.

Requirements

This repository uses pre-commit and go-critic for maintaining code quality. Installing them is not mandatory, but it helps in avoiding the problems you'd otherwise encounter after opening a pull request as they are run by automated tests for all PRs.

Development quickstart

To begin development, first fork the repository to your own account, clone it and begin making changes.

git clone [email protected]/username/upcloud-cli.git
cd upcloud-cli
pre-commit install

Make the changes with your favorite editor. Once you're done, create a new branch and push it back to Github.

git checkout -b <branch-name>
<add your changes, "git status" helps>
git commit -m "New feature: create a new server in the nearest zone if not specified"
git push --set-upstream <branch-name>

After pushing the new branch, browse to your fork of the repository in GitHub and create a pull request from there. Once the pull request is created, please make changes to your branch based on the comments & discussion in the PR.

License

MIT license