UpCloud CLI (upctl) is a command-line interface tool designed to manage and interact with UpCloud services seamlessly. It empowers users to control cloud resources such as servers, storage, backups, and networking directly from the terminal or scripts.
Key Features:
Resource Management: Efficiently create, modify, and delete servers, storage, backups, and network configurations.
API Integration: Sends API requests on behalf of the user, simplifying interactions with UpCloud services.
CI/CD Integration: Designed to integrate smoothly into continuous integration and deployment pipelines.
Audience & Benefit:
Ideal for developers, DevOps engineers, and system administrators who require efficient control over cloud infrastructure. By automating resource management through the command line, upctl helps streamline workflows, reduce manual errors, and simplify integration with existing tools or scripts. It can be installed via winget for easy setup.
README
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.
Getting started
For instructions on how to install upctl, configure credentials, and run commands, see Getting started instructions in the documentation.
Exit codes
Exit code communicates success or the type and number of failures. Possible exit codes of upctl are:
Exit code
Description
0
Command(s) executed successfully.
1 - 99
Number of failed executions. For example, if stopping four servers and API returns error for one of the request, exit code will be 1.
100 -
Other, non-execution related, errors. For example, required flag missing.
Examples
Every command has a --help parameter that can be used to print detailed usage instructions and examples on how to use the command. For example, run upctl network list --help, to display usage instructions and examples for upctl network list command.
See examples directory for examples on more complex use-cases.
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.
Note that documentation in GitHub pages is versioned with mike. See docs workflow for more details. The versions are main and latest:
The main version is updated on every push to main branch. It is useful for reviewing new commands and features. The main version often contains instructions for features that are not yet released.
The latest version is updated on every release. It is the default version and only contains released commands and features to avoid confusion for end-users.
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
You need a Go version 1.20+ installed on your development machine.
Use make to build and test the CLI. Makefile help can be found by running make help.
make help
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 git@github.com/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
git commit -m "New feature: create a new server in the nearest zone if not specified"
git push --set-upstream
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.
