diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..3d7e829d1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,14 @@ +# Documentation + +Welcome to the documentation for the **Hetzner Cloud CLI**. + +This documentation is written and organized following the [Diátaxis](https://diataxis.fr/) guidelines. Below you can find a high-level overview of where to look for certain things: + +- [Tutorials](tutorials) +- [Guides](guides) +- [Reference](reference/hcloud.md) + +## Getting help + +- 🐛 Report bugs using [our issue tracker](https://github.com/hetznercloud/cli/issues/new?template=bug.yaml). +- 🙋 If you need help, reach us using the [Support Center](https://console.hetzner.cloud/support). diff --git a/docs/guides/README.md b/docs/guides/README.md new file mode 100644 index 000000000..3d2bc6f93 --- /dev/null +++ b/docs/guides/README.md @@ -0,0 +1,5 @@ +# Guides + +This folder contains guides on how to accomplish specific tasks with the Hetzner Cloud CLI. + +- [Using output options](using-output-options.md) diff --git a/docs/guides/using-output-options.md b/docs/guides/using-output-options.md new file mode 100644 index 000000000..a69f7c675 --- /dev/null +++ b/docs/guides/using-output-options.md @@ -0,0 +1,167 @@ +# Using output options + +The CLI allows you to customize the output format of some commands using the `--output` flag. +This guide shows you how to use this feature and use it in combination with other tools. + +## JSON + +`describe`, `list` and `create` commands support JSON output format. To use it, simply add the `--output json` flag to your command. + +For example, to get the details of a location in JSON format, you can use the following command: + +```bash +$ hcloud location describe fsn1 --output json +{ + "id": 1, + "name": "fsn1", + "description": "Falkenstein DC Park 1", + "country": "DE", + "city": "Falkenstein", + "latitude": 50.47612, + "longitude": 12.370071, + "network_zone": "eu-central" +} +``` + +You can combine this with other tools to process the output. For example, you can use `jq` to filter the output: + +```bash +$ hcloud location describe fsn1 --output json | jq '.name' +"fsn1" +``` + +```bash +$ hcloud location describe fsn1 --output json | jq '{id, name}' +{ + "id": 1, + "name": "fsn1" +} +``` + +`list` commands return a list of objects in JSON format. For example, to get a list of all locations in JSON format, you can use the following command: + +```bash +$ hcloud location list --output json +[ + { + "id": 1, + "name": "fsn1", + "description": "Falkenstein DC Park 1", + "country": "DE", + "city": "Falkenstein", + "latitude": 50.47612, + "longitude": 12.370071, + "network_zone": "eu-central" + }, + { + "id": 2, + "name": "nbg1", + "description": "Nuremberg DC Park 1", + "country": "DE", + "city": "Nuremberg", + "latitude": 49.452102, + "longitude": 11.076665, + "network_zone": "eu-central" + }, + ... +] +``` + +Once again, you can use `jq` to filter the output. Following example shows how to get the names of all locations of which the network zone is `eu-central`: + +```bash +$ hcloud location list --output json | jq '[.[] | select(.network_zone == "eu-central") | .name]' +[ + "fsn1", + "nbg1", + "hel1" +] +``` + +## YAML + +`describe`, `list` and `create` commands support YAML output format as well. + +```bash +$ hcloud location describe fsn1 --output yaml +id: 1 +name: fsn1 +description: Falkenstein DC Park 1 +country: DE +city: Falkenstein +latitude: 50.47612 +longitude: 12.370071 +network_zone: eu-central +``` + +For YAML, you can use `yq` instead of `jq`. + + +```bash +$ hcloud location list --output yaml | yq '.[] | [{"id": .id, "name": .name}]' +- id: 1 + name: fsn1 +- id: 2 + name: nbg1 +- id: 3 + name: hel1 +- id: 4 + name: ash +- id: 5 + name: hil +- id: 6 + name: sin +``` + +## Go Template Format + +`describe` commands support the Go string template format as well. You can read up on the syntax in the +[Go documentation](https://pkg.go.dev/text/template/). The data structures passed to the template are defined +by our API and can be found in [hcloud-go](https://pkg.go.dev/github.com/hetznercloud/hcloud-go/v2/hcloud/schema). + +For example, you could obtain the number of cores of a server using the following command: + +```bash +$ hcloud server describe my-server --output format='{{.ServerType.Cores}}' +2 +``` + +## Table options + +`list` commands support table options as well. These options allow you to customize the output format of the output table, +if not using JSON or YAML. + +> [!NOTE] +> You can also combine both of the below options to use them at once: ``--output noheader --output columns=id,name,network_zone`` + +### noheader + +This option removes the header from the output table. + +```bash +$ hcloud location list --output noheader +1 fsn1 Falkenstein DC Park 1 eu-central DE Falkenstein +2 nbg1 Nuremberg DC Park 1 eu-central DE Nuremberg +3 hel1 Helsinki DC Park 1 eu-central FI Helsinki +4 ash Ashburn, VA us-east US Ashburn, VA +5 hil Hillsboro, OR us-west US Hillsboro, OR +6 sin Singapore ap-southeast SG Singapore +``` + +### columns + +This option allows you to filter by columns. + +```bash +$ hcloud location list --output columns=id,name,network_zone +ID NAME NETWORK ZONE +1 fsn1 eu-central +2 nbg1 eu-central +3 hel1 eu-central +4 ash us-east +5 hil us-west +6 sin ap-southeast +``` + +Using the ``--help`` flag will show you a list of all available columns for this command. Note that these might include +more than the default columns. diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md new file mode 100644 index 000000000..b1bc701ff --- /dev/null +++ b/docs/tutorials/README.md @@ -0,0 +1,6 @@ +# Tutorials + +This folder contains tutorials for the Hetzner Cloud CLI. + +- [Setup the hcloud CLI](setup-hcloud-cli.md) +- [Creating a server](create-a-server.md) diff --git a/docs/tutorials/create-a-server.md b/docs/tutorials/create-a-server.md new file mode 100644 index 000000000..8c15b3801 --- /dev/null +++ b/docs/tutorials/create-a-server.md @@ -0,0 +1,108 @@ +# Creating a server + +This tutorial covers the process of creating a server using the Hetzner Cloud CLI. It includes creating an SSH Key, +uploading it, creating a Server and then connecting to it via SSH. + +## Prerequisites + +- A functioning installation of the [hcloud CLI](setup-hcloud-cli.md), with a valid active context. + +## 1. Create an SSH Key + +### 1.1 Generate an SSH Key + +While an SSH key is not strictly required to create a server, it is highly recommended for secure access. +If you don't have an SSH key yet, you can generate one using the following command: + +```bash +ssh-keygen -t ed25519 -f ~/.ssh/hcloud +``` + +Your private key will now be located at `~/.ssh/hcloud`. **Do not share your private key with anyone!** + +### 1.2 Upload the SSH Key + +You can upload your SSH key to Hetzner Cloud using the following command: + +```bash +hcloud ssh-key create --name my-ssh-key --public-key-from-file ~/.ssh/hcloud.pub +``` + +> [!TIP] +> You can set this SSH key as the default SSH key for your context using the following command: +> ```bash +> hcloud config set default-ssh-keys my-ssh-key +> ``` + +## 2. Create a Server + +### 2.1 Pick a Server Type + +Before creating a server, you need to choose a server type. You can list all available server types using the following command: + +```bash +hcloud server-type list +``` + +For this example we will use the `cpx11` server type. +You can view the details of this server type using the following command: + +```bash +hcloud server-type describe cpx11 +``` + +### 2.2 Pick an Image + +You need to choose an image for your server. You can list all available images using the following command: + +```bash +hcloud image list +``` + +There are many images available, including various Linux distributions and pre-configured app images. +For this example we will use the `ubuntu-24.04` image. + +### 2.3 Pick a Location (Optional) + +You can choose a location for your server. You can list all available locations using the following command: + +```bash +hcloud location list +``` + +If you don't specify a location, one will be chosen for you. This is what we will do in this example. + +### 2.4 Create the Server + +Now you can create the server using the following command: + +```bash +hcloud server create --name my-server --type cpx11 --image ubuntu-24.04 --ssh-key my-ssh-key +``` + +If you set the SSH key as the default SSH key for your context, you can omit the `--ssh-key` flag. +After the server was created, you will see information about the server, including its IP address. + +## 3. Connect to the Server + +You can connect to the server using SSH. The CLI contains a built-in utility to do this: + +```bash +hcloud server ssh my-server -i ~/.ssh/hcloud +``` + +This command will open an SSH connection to the server using the private key you generated earlier. + +## 4. Clean Up + +After you are done with the server, you can delete it using the following command: + +```bash +hcloud server delete my-server +``` + +You can also delete the SSH key using the following command: + +```bash +hcloud ssh-key delete my-ssh-key +``` diff --git a/docs/tutorials/setup-hcloud-cli.md b/docs/tutorials/setup-hcloud-cli.md new file mode 100644 index 000000000..5f4e8a359 --- /dev/null +++ b/docs/tutorials/setup-hcloud-cli.md @@ -0,0 +1,163 @@ +# Setup the hcloud CLI + +This tutorial will guide you through the process of setting up the hcloud CLI on your local machine. + +## Prerequisites + +Before you begin, ensure you have the following: + +- A [Hetzner Cloud account](https://console.hetzner.cloud). + +## 1. Install the hcloud CLI + +### 1.1 Manual installation + +You can download pre-built binaries from our [GitHub releases](https://github.com/hetznercloud/cli/releases). +Install them by extracting the archive and moving the binary to a directory in your `PATH`. + +On a 64-bit Linux system, it could look something like this: + +```bash +curl -LO https://github.com/hetznercloud/cli/releases/download/v1.50.0/hcloud-darwin-amd64.tar.gz +sudo tar -C /usr/local/bin -xzf hcloud-darwin-amd64.tar.gz +rm hcloud-darwin-amd64.tar.gz +``` + +### 1.2 Installation using Go + +If you have Go installed, you can also install hcloud CLI from source using the following command: + +```bash +go install github.com/hetznercloud/cli@latest +``` + +> [!NOTE] +> Binaries built with Go will not have the correct version embedded. + +> [!NOTE] +> Both of the above installation methods do not provide automatic updates. Please make sure to keep your installation up to date manually. + +### 1.3 Installation using Homebrew + +On Linux and macOS you can also install the hcloud CLI using Homebrew: + +```bash +brew install hcloud +``` + +### 1.4 Installation using scoop + +On Windows, you can install `hcloud` using scoop: + +```bash +scoop install hcloud +``` + +--- + +> [!WARNING] +> Debian-based distributions (using apt) provide outdated versions of the hcloud CLI. +> Please consider one of the other installation methods. + +## 2. (Optional) Setup auto-completion + +hcloud CLI offers auto-completion for bash, zsh, fish and PowerShell. It is recommended to enable it for a better user experience. + +### 2.1 Bash + +To load completions into the current shell execute: + + source <(hcloud completion bash) + +In order to make the completions permanent, append the line above to +your .bashrc. + +### 2.2 Zsh + +If shell completions are not already enabled for your environment need +to enable them. Add the following line to your ~/.zshrc file: + + autoload -Uz compinit; compinit + +To load completions for each session execute the following commands: + + mkdir -p ~/.config/hcloud/completion/zsh + hcloud completion zsh > ~/.config/hcloud/completion/zsh/_hcloud + +Finally add the following line to your ~/.zshrc file, *before* you +call the compinit function: + + fpath+=(~/.config/hcloud/completion/zsh) + +In the end your ~/.zshrc file should contain the following two lines +in the order given here. + + fpath+=(~/.config/hcloud/completion/zsh) + # ... anything else that needs to be done before compinit + autoload -Uz compinit; compinit + # ... + +You will need to start a new shell for this setup to take effect. + +### 2.3 Fish + +To load completions into the current shell execute: + + hcloud completion fish | source + +In order to make the completions permanent execute once: + + hcloud completion fish > ~/.config/fish/completions/hcloud.fish + +### 2.4 PowerShell + +To load completions into the current shell execute: + + PS> hcloud completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, run +and source this file from your PowerShell profile. + + PS> hcloud completion powershell > hcloud.ps1 + +## 3. Create a context + +The hcloud CLI uses contexts to manage multiple Hetzner Cloud tokens and set configuration preferences. + +First, you need to create an API token. +Follow the instructions in the [Hetzner Cloud documentation](https://docs.hetzner.com/cloud/api/getting-started/generating-api-token) to create your project API token. + +Once you have your token, you can create a context using the following command: + +```bash +hcloud context create +``` + +Ideally, keep the context name similar to the project name so you can easily identify it later. + +When prompted, enter the API token you created earlier. Your context should now be created and activated. + +## 4. Verify everything works + +To verify that the hcloud CLI is working correctly, you can run the following command: + +```bash +hcloud datacenter list +``` + +You should see something like this: + +```plaintext +ID NAME DESCRIPTION LOCATION +2 nbg1-dc3 Nuremberg 1 virtual DC 3 nbg1 +3 hel1-dc2 Helsinki 1 virtual DC 2 hel1 +4 fsn1-dc14 Falkenstein 1 virtual DC 14 fsn1 +5 ash-dc1 Ashburn virtual DC 1 ash +6 hil-dc1 Hillsboro virtual DC 1 hil +7 sin-dc1 Singapore virtual DC 1 sin +``` + +If you see this output, congratulations! You have successfully set up the hcloud CLI on your local machine. + +If there are any problems, make sure you followed all steps of this tutorial correctly. If there still are problems, +you can reach out to our [Support](https://console.hetzner.cloud/support) to get help.