Improve command usage descriptions (continued from staled #108)

[com2]

I did not think that commenting would reopen #108 so here another attempt to draw your attention.

hcloud server create-image --help is not clear about the use of --label and it was impossible for me to create a valid command line with that "flag". For instance:

$ hcloud server create-image --type snapshot --label name=upgrade-ready --label ts="$timestamp" --description "upgrade-ready $timestamp" $svrid
hcloud: invalid input in field 'labels' (invalid_input)

I hoped to create a bash script to make things a bit easier but with the lack of documentation it would be better to "stale" not only #108 but also the whole project. It would force some to continue with Python or Go and me to abandon and do it all manually.

[com2]

apparently labels in hcloud cli does not accept any bash variable. I tried to work around the issue and tried:

$ hcloud image add-label -o $imageID ts=$ts
hcloud: invalid input in field 'labels' (invalid_input)
$ hcloud image add-label -o $imageID ts="$ts"
hcloud: invalid input in field 'labels' (invalid_input)
$ hcloud image add-label -o $imageID "ts=$ts"
hcloud: invalid input in field 'labels' (invalid_input)

Turned out that labels do not accept certain characters. After cleaning up the $ts variable the first line of the example started working. Looks like that server create-image --label for the same reason. I guess that only alphanumerical and underscore is accepted.

[com2]

In hcloud image enable-protection --help the expected PROTECTIONLEVEL values are not listed.

[apricote]

Hey @com2, please keep posting any usability issues you find, getting actual feedback and where issues arise is important to us.

For labels in particular, the rules for what is and what is not allowed are documented in our API docs: https://docs.hetzner.cloud/#labels

Labels are key/value pairs that can be attached to all resources.

Valid label keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be a string of 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).

Valid label values must be a string of 63 characters or less and must be empty or begin and end with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.

The hetzner.cloud/ prefix is reserved and cannot be used.

[github-actions[bot]]

This issue has been marked as stale because it has not had recent activity. The bot will close the issue if no further action occurs.

[github-actions[bot]]

This issue has been marked as stale because it has not had recent activity. The bot will close the issue if no further action occurs.

[phm07]

We already improved the command usage descriptions in #709. They now uniformly comply to the docopt standard. The error you see comes straight from the API because we currently do not do any validation on labels before sending the request. I agree that the API error is not very helpful in this case. We should probably add custom validation here (and in many other places).