Skip to content

Commit 89b2a6a

Browse files
phm07phm07
authored
docs: link readme to docs (#1059)
This PR cleans up the readme, links to the docs where needed and also moves the configuration help text to `docs/reference`.
1 parent 2123b22 commit 89b2a6a

3 files changed

Lines changed: 30 additions & 189 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 189 deletions
Original file line numberDiff line numberDiff line change
@@ -10,197 +10,12 @@
1010

1111
[![asciicast](https://asciinema.org/a/157991.png)](https://asciinema.org/a/157991)
1212

13-
## Installation
13+
## Docs
1414

15-
You can download pre-built binaries for Linux, FreeBSD, macOS, and Windows on
16-
the [releases page](https://github.com/hetznercloud/cli/releases).
15+
- See [setting up hcloud](docs/tutorials/setup-hcloud-cli.md) for instructions on how to install and configure the CLI.
16+
- See the [manual](docs/reference/manual/hcloud.md) for a list of all available commands and their options.
1717

18-
On macOS and Linux, you can install `hcloud` via [Homebrew](https://brew.sh/):
19-
20-
brew install hcloud
21-
22-
23-
On Windows, you can install `hcloud` via [Scoop](https://scoop.sh/)
24-
25-
scoop install hcloud
26-
27-
### Third-party packages
28-
29-
There are unofficial packages maintained by third-party users. Please note
30-
that these packages aren’t supported nor maintained by Hetzner Cloud and
31-
may not always be up-to-date. Downloading the binary or building from source
32-
is still the recommended install method.
33-
34-
### Build manually
35-
36-
If you have Go installed, you can build and install the latest version of
37-
`hcloud` with:
38-
39-
go install github.com/hetznercloud/cli/cmd/hcloud@latest
40-
41-
> Binaries built in this way do not have the correct version embedded. Use our
42-
prebuilt binaries or check out [`.goreleaser.yml`](.goreleaser.yml) to learn
43-
how to embed it yourself.
44-
45-
### Docker
46-
47-
A docker image is published at `hetznercloud/cli`.
48-
49-
```bash
50-
docker run --rm -e HCLOUD_TOKEN="<your token>" hetznercloud/cli:latest <command>
51-
```
52-
53-
If you want to use (and persist) your configuration, you can mount it to `/config.toml`:
54-
```bash
55-
docker run --rm -v ~/.config/hcloud/cli.toml:/config.toml hetznercloud/cli:latest <command>
56-
```
57-
58-
## Getting Started
59-
60-
1. Visit the Hetzner Cloud Console at [console.hetzner.cloud](https://console.hetzner.cloud/),
61-
select your project, and create a new API token.
62-
63-
2. Configure the `hcloud` program to use your token:
64-
65-
hcloud context create my-project
66-
67-
3. You’re ready to use the program. For example, to get a list of available server
68-
types, run:
69-
70-
hcloud server-type list
71-
72-
See `hcloud help` for a list of commands.
73-
74-
You can also check out the [command reference](docs/reference) for help.
75-
76-
## Shell Completion
77-
78-
`hcloud` provides completions for various shells.
79-
80-
### Bash
81-
82-
To load completions into the current shell execute:
83-
84-
source <(hcloud completion bash)
85-
86-
In order to make the completions permanent, append the line above to
87-
your `.bashrc`.
88-
89-
### Zsh
90-
91-
If shell completions are not already enabled for your environment need
92-
to enable them. Add the following line to your `~/.zshrc` file:
93-
94-
autoload -Uz compinit; compinit
95-
96-
To load completions for each session execute the following commands:
97-
98-
mkdir -p ~/.config/hcloud/completion/zsh
99-
hcloud completion zsh > ~/.config/hcloud/completion/zsh/_hcloud
100-
101-
Finally, add the following line to your `~/.zshrc` file, *before* you
102-
call the `compinit` function:
103-
104-
fpath+=(~/.config/hcloud/completion/zsh)
105-
106-
In the end your `~/.zshrc` file should contain the following two lines
107-
in the order given here.
108-
109-
fpath+=(~/.config/hcloud/completion/zsh)
110-
# ... anything else that needs to be done before compinit
111-
autoload -Uz compinit; compinit
112-
# ...
113-
114-
You will need to start a new shell for this setup to take effect.
115-
116-
### Fish
117-
118-
To load completions into the current shell execute:
119-
120-
hcloud completion fish | source
121-
122-
In order to make the completions permanent execute once:
123-
124-
hcloud completion fish > ~/.config/fish/completions/hcloud.fish
125-
126-
### PowerShell:
127-
128-
To load completions into the current shell execute:
129-
130-
PS> hcloud completion powershell | Out-String | Invoke-Expression
131-
132-
To load completions for every new session, run
133-
and source this file from your PowerShell profile.
134-
135-
PS> hcloud completion powershell > hcloud.ps1
136-
137-
## Output configuration
138-
139-
You can control output via the `-o` option:
140-
141-
* For `list` commands, you can specify `-o noheader` to omit the table header.
142-
143-
* For `list` commands, you can specify `-o columns=id,name` to only show certain
144-
columns in the table.
145-
146-
* For `describe` commands, you can specify `-o json` to get a JSON representation
147-
of the resource. The schema is identical to those in the Hetzner Cloud API which
148-
are documented at [docs.hetzner.cloud](https://docs.hetzner.cloud).
149-
150-
* For `create` commands, you can specify `-o json` to get a JSON representation
151-
of the API response. API responses are documented at [docs.hetzner.cloud](https://docs.hetzner.cloud).
152-
In contrast to `describe` commands, `create` commands can return extra information, for example
153-
the initial root password of a server.
154-
155-
* For `describe` commands, you can specify `-o format={{.ID}}` to format output
156-
according to the given [Go template](https://golang.org/pkg/text/template/).
157-
The template’s input is the resource’s corresponding struct in the
158-
[hcloud-go](https://godoc.org/github.com/hetznercloud/hcloud-go/hcloud) library.
159-
160-
## Configuring hcloud
161-
162-
The hcloud CLI tool can be configured using following methods:
163-
1. Configuration file
164-
2. Environment variables
165-
3. Command line flags
166-
167-
A higher number means a higher priority. For example, a command line flag will
168-
always override an environment variable.
169-
170-
The configuration file is located at `~/.config/hcloud/cli.toml` by default
171-
(On Windows: `%APPDATA%\hcloud\cli.toml`). You can change the location by setting
172-
the `HCLOUD_CONFIG` environment variable or the `--config` flag. The configuration file
173-
stores global preferences, the currently active context, all contexts and
174-
context-specific preferences. Contexts always store a token and can optionally have
175-
additional preferences which take precedence over the globally set preferences.
176-
177-
However, a config file is not required. If no config file is found, the CLI will
178-
use the default configuration. Overriding options using environment variables allows the
179-
hcloud CLI to function in a stateless way. For example, setting `HCLOUD_TOKEN` is
180-
already enough in many cases.
181-
182-
You can use the `hcloud config` command to manage your configuration, for example
183-
to get, list, set and unset configuration options and preferences. You can view a list
184-
of all available options and preferences by running `hcloud config --help`.
185-
186-
## Examples
187-
188-
### List all servers
189-
190-
```
191-
$ hcloud server list
192-
ID NAME STATUS IPV4
193-
210216 test1 running 78.46.122.12
194-
210729 ubuntu-8gb-nbg1-dc3-1 running 94.130.177.158
195-
```
196-
197-
### Create a server
198-
199-
```
200-
$ hcloud server create --name test --image debian-9 --type cx22 --ssh-key demo
201-
7s [====================================================================] 100%
202-
Server 325211 created
203-
```
18+
For additional information, see the [documentation](docs).
20419

20520
## License
20621

‎docs/reference/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,4 @@
33
In this directory you will find the reference documentation for the hcloud CLI.
44

55
- [Command manual](manual/hcloud.md)
6+
- [Configuration](configuration.md)

‎docs/reference/configuration.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Configuring hcloud
2+
3+
The hcloud CLI tool can be configured using following methods:
4+
1. Configuration file
5+
2. Environment variables
6+
3. Command line flags
7+
8+
A higher number means a higher priority. For example, a command line flag will
9+
always override an environment variable.
10+
11+
The configuration file is located at `~/.config/hcloud/cli.toml` by default
12+
(On Windows: `%APPDATA%\hcloud\cli.toml`). You can change the location by setting
13+
the `HCLOUD_CONFIG` environment variable or the `--config` flag. The configuration file
14+
stores global preferences, the currently active context, all contexts and
15+
context-specific preferences. Contexts always store a token and can optionally have
16+
additional preferences which take precedence over the globally set preferences.
17+
18+
However, a config file is not required. If no config file is found, the CLI will
19+
use the default configuration. Overriding options using environment variables allows the
20+
hcloud CLI to function in a stateless way. For example, setting `HCLOUD_TOKEN` is
21+
already enough in many cases.
22+
23+
You can use the `hcloud config` command to manage your configuration, for example
24+
to get, list, set and unset configuration options and preferences. You can view a list
25+
of all available options and preferences [here](manual/hcloud_config.md#synopsis).

0 commit comments

Comments
 (0)