hetznercloud / cli

A command-line interface for Hetzner Cloud

hcloud: Command-line interface for Hetzner Cloud

hcloud is a command-line interface for interacting with Hetzner Cloud.

Installation

You can download pre-built binaries for Linux, FreeBSD, macOS, and Windows on the releases page.

On macOS and Linux, you can install hcloud via Homebrew:

brew install hcloud

On Windows, you can install hcloud via Scoop

scoop install hcloud

Third-party packages

There are unofficial packages maintained by third-party users. Please note that these packages aren’t supported nor maintained by Hetzner Cloud and may not always be up-to-date. Downloading the binary or building from source is still the recommended install method.

Build manually

If you have Go installed, you can build and install the latest version of hcloud with:

go install github.com/hetznercloud/cli/cmd/hcloud@latest

Binaries built in this way do not have the correct version embedded. Use our prebuilt binaries or check out .goreleaser.yml to learn how to embed it yourself.

Getting Started

1. Visit the Hetzner Cloud Console at console.hetzner.cloud, select your project, and create a new API token.

2. Configure the hcloud program to use your token:

   hcloud context create my-project
   

3. You’re ready to use the program. For example, to get a list of available server types, run:

   hcloud server-type list
   

See hcloud help for a list of commands.

Shell Completion

hcloud provides completions for various shells.

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.

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.

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

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

Output configuration

You can control output via the -o option:

• For list commands, you can specify -o noheader to omit the table header.

• For list commands, you can specify -o columns=id,name to only show certain columns in the table.

• For describe commands, you can specify -o json to get a JSON representation of the resource. The schema is identical to those in the Hetzner Cloud API which are documented at docs.hetzner.cloud.

• For create commands, you can specify -o json to get a JSON representation of the API response. API responses are documented at docs.hetzner.cloud. In contrast to describe commands, create commands can return extra information, for example the initial root password of a server.

• For describe commands, you can specify -o format={{.ID}} to format output according to the given Go template. The template’s input is the resource’s corresponding struct in the hcloud-go library.

Configuring hcloud

The hcloud CLI tool can be configured using following methods:

1. Configuration file
2. Environment variables
3. Command line flags

A higher number means a higher priority. For example, a command line flag will always override an environment variable.

The configuration file is located at ~/.config/hcloud/cli.toml by default (On Windows: %APPDATA%\hcloud\cli.toml). You can change the location by setting the HCLOUD_CONFIG environment variable or the --config flag. The configuration file stores global preferences, the currently active context, all contexts and context-specific preferences. Contexts always store a token and can optionally have additional preferences which take precedence over the globally set preferences.

However, a config file is not required. If no config file is found, the CLI will use the default configuration. Overriding options using environment variables allows the hcloud CLI to function in a stateless way. For example, setting HCLOUD_TOKEN is already enough in many cases.

You can use the hcloud config command to manage your configuration, for example to get, list, set and unset configuration options and preferences. You can view a list of all available options and preferences by running hcloud config --help.

Examples

List all servers

$ hcloud server list
ID       NAME                    STATUS    IPV4
210216   test1                   running   78.46.122.12
210729   ubuntu-8gb-nbg1-dc3-1   running   94.130.177.158

Create a server

$ hcloud server create --name test --image debian-9 --type cx22 --ssh-key demo
   7s [====================================================================] 100%
Server 325211 created

License

MIT license

cli's Issues

cloud-init support when creating server

Hi, is the option --user-data supported when creating server ?

Implement server enable-backup command

hcloud server enable-backup ID --window WINDOW

Fix datetime output

$ hcloud image describe ubuntu-16.04 
...
Created:	2018-01-15 11:34:45 +0000 +0000 (1 week ago)
...

Having the offset printed twice looks odd. We should print it either as UTC or in the user’s local time.

Create an asciinema screencast

hcloud floating-ip create help: Show valid types. Consider default value

>hcloud floating-ip create --help
Create a Floating IP

Usage:
  hcloud floating-ip create FLAGS

Flags:
      --description string     Description
  -h, --help                   help for create
      --home-location string   Home location
      --server string          Server to assign Floating IP to
      --type string            Type

For type we should show the valid choices (ipv4, ipv6) in the help text.

How about making ipv4 the default for type?

Feature Idea: Option to set reverse lookup to instance name

In the case of spawning a lot of instances, it may be useful to set the reverse lookup to the instance name, if the instance name is a DNS hostname.

This would prevent to change in XYZ instances manually in the console or with the API.

server location / datacenter not printed in describe

It is not possbile to get the server location and datacenter via the CLI neither with

hcloud server list

nor

hcloud server describe xxx

While the API provides the information.

Context handling still not use friendly

Most users seem to assume that after creating a context it is automatically used. Maybe we can satisfy this expectation?

Even if we do not decide to auto-select recently created context we should print a message after context creation which clearly indicates what has happened:

Either

• new context created but you will need to run hcloud context x use to activate or
• new context created and it was automatically activated

zsh auto-complete is partialy borken

Just builded the client on a ubuntu-16.04 machine (while being connectec via ssh) with golang-1.9 the auto-completion sometimes fails (for example auto completing the ssh-key inside the server create) will lead to the following error:
_handle_flag:27: bad math expression: illegal character: ^[

Check if there is an active context

Don’t just say “unauthorized”. 😕

Allow name in ssh-key {describe|delete}

hcloud ssh-key describe NAME
hcloud ssh-key delete NAME

Implement iso describe command

hcloud iso describe ID

hcloud image list: Add optional argument for image type

Right now hcloud image list seems to show images of all types. We should consider adding an optional argument --type which enables you to only list images of a certain type, e.g.

hcloud image list --type system will only show system images

Check completion is working for all commands

Following the "Getting started" guide leads to error

I'm under Windows 10 using "hcloud-windows-amd64-v1.3.1.zip" release.

I followed the 3 steps from https://github.com/hetznercloud/cli#getting-started

Result: hcloud: unable to authenticate your token (unauthorized)

For some reason hcloud is not using/accepting my token.

Implement floating-ip update command

hcloud floating-ip update ID --description DESCRIPTION

Check if we can support Windows without much effort

It builds, but there are problems:

• hcloud: config file path unknown (Windows has no $HOME)

Implement server update command

hcloud server update ID --name NAME

Implement datacenter list command

hcloud datacenter list

Implement server change-type command

hcloud server change-type ID TYPE

support non-interactive input on more functions as pipe or parameter

like initial setup cannot be scripted:

# echo "XXXXXXXX_TOKEN_XXXXXXXX" | hcloud context create Testing
Token:
hcloud: inappropriate ioctl for device

Automatically active context when first context is created

When there are no contexts and the first one is created, automatically activate it.

Progress bar not shown correctly on Windows

On Windows, the progress bar is only shown correctly when the prompt is slightly larger than the default size (in width). Otherwise the progress bar is printed multiple times.

Vendor dependencies

Using dep.

Release v1.0.0

• Pin github.com/hetznercloud/hcloud-go to v1.0.0 in Gopkg.toml
• Set Version constant to 1.0.0
• Update hcloud-go once v1.0.0 of hcloud-go is re-tagged

Optional

• Add completions to Homebrew formula
• Get the Homebrew formula into the main library

Use noheader output option for completion

Use -o noheader instead deleting the header with grep -v '^ID'.

image {list|describe}: handle 0 image size

Show - when it’s zero.

Implement location list command

hcloud location list

Show the assigned server name and the id in floatingip describe

Output configuration

We want to be able to control how output is formatted.

For example, we want to disable printing the column names (first line) to be able to do things like:

$ hcloud server list | wc -l
5

Or to specify which columns are printed:

$ hcloud server list
ID
1
2
3

In the future we might also want to support other output formats (JSON, YAML).

Proposal

Output is completely controlled via the -o option which can be specified multiple times with different values. A value is either just a key key or a key-value pair key=value.

Examples

To disable printing column names:

$ hcloud -o nocolumns server list

To only print the ID and name columns and sort by name:

$ hcloud -o columns=id,name -o sort=name:desc server list

To output JSON:

$ hcloud -o format=json server list

The option format=table is the default output format.

Implement server attach-iso command

hcloud server attach-iso ID ISO

server describe: Floating IP section is misaligned

  Floating IPs:
  - ID:		49
    Description:	dsds
    IP:		2a01:4f8:1c17:2c::

add metrics

Hiho,

maybe I'm blind, but the most obvious point seems to be missing: metrics. This is surprising, since the API has a query for that: https://docs.hetzner.cloud/#resources-servers-get-2

Would love to see that for daily reports :)

floatingip create: do not require home location when server is provided

Structured access to fields (JSON, Go templates)

Sometimes you want to use the CLI in a shell script to get some information, but parsing the output is obviously a bad idea. We should consider adding JSON support so you can access information in a structured way.

Have a look at how docker inspect enables this: https://docs.docker.com/engine/reference/commandline/inspect/#extended-description

Implement image update command

hcloud image update ID --description DESCRIPTION --type TYPE

Update readme

An asciinema showing the CLI in action would be nice.

Windows build: Convert textfile line endings to Windows

The builds include textfiles. Their line endings are currently in unix format. When building the Windows version we should convert them to the Windows format.

Maybe use one of the methods from http://www.microhowto.info/howto/convert_the_line_endings_in_a_text_file_from_unix_to_dos_format.html ?

hcloud context create: Add optional --token flag

When using hcloud in a CI environment, the user should be able to pass the token via environment variables.

hcloud: server limit reached

Hi, when using hcloud to create a new server i get this error: "Server limit reached" Was it this ?

Show prefix for IPv6 addresses

$ hcloud floating-ip list     
ID   TYPE   DESCRIPTION   IP                   HOME   SERVER   DNS
49   ipv6   dsds          2a01:4f8:1c17:2c::   fsn1   -        -

Fix it everywhere.

Implement iso list command

hcloud iso list

Allow specifying context via HCLOUD_CONTEXT

$ hcloud context active
foo
$ HCLOUD_CONTEXT=bar hcloud context active
bar

Implement server disable-backup command

hcloud server disable-backup ID

image update ID not autocompleted

hcloud image update <TAB>

does not complete image ID.

Conceal token when creating new context

Like when entering a password on the command line. There is probably already a library providing this.

Consider asking for confirmation when deleting resources

• server delete
• floating-ip delete
• image delete
• ssh-key delete

Implement server detach-iso command

hcloud server detach-iso ID

server update: require at least one parameter

$ hcloud server update test1
Server test1 updated

Implement server rebuild command

hcloud server rebuild ID --image IMAGE