Improve documentation for the CLI regarding tokens and config file

[gbirke]

When I set up Woodpecker for the first time and wanted to add a secret via CLI, I struggled with authentication. This is a description of what I experienced and how the user experience could be improved (mostly via documentation changes):

1. I did not know where the "token" comes from. I tried the GitHub access token, the word "secret" (from WOODPECKER_GRPC_SECRET) until I dimly remembered prior experience with Drone CI and was able to log in and find my token in the user settings. It would be nice, if the CLI documentation mentioned where you can get the token from.
2. I hoped to generate a basic configuration file with woodpecker-cli setup. But I executed the CLI on a remote machine and it always failed to continue after entering the server URL because it tried to open a browser. Here I'd wish for one or several of the following changes:
   • Better handling of of failed browser opening (see also Show CLI commands arguments in documentation #3456 ), printing the URL and continuing the process instead.
   • Mentioning again where the token comes from (e.g. "Please log in at <server_url>" and get the token from the "CLI & API" section of your user settings).
   • A hint in the help where the config file is usually written (e.g. ~/.config/woodpecker/config.json on Linux)
   • Showing an example configuration JSON in the CLI help, to be able to manually create the config file without running woodpecker-cli setup
   • (Re)Generating the config file with woodpecker-cli setup by passing environment variables or parameters

If I read #3456 correctly, the automatically generated Markdown documentation for the CLI will go away in the future. Let's take the opportunity to craft more meaningful documentation page and better help.

I have resolved all my issues and I'm now a happy CLI user, but I would wish the path for others to be less rocky.

[anbraten]

Thanks for the detailed feedback.

I did not know where the "token" comes from. I tried the GitHub access token, the word "secret" (from WOODPECKER_GRPC_SECRET) until I dimly remembered prior experience with Drone CI and was able to log in and find my token in the user settings. It would be nice, if the CLI documentation mentioned where you can get the token from.

How did you found out about the cli? Where would be a nice entry point to mention this from your pov?

Better handling of of failed browser opening (see also #3456 ), printing the URL and continuing the process instead.

This one should be easily doable by handling the error and showing an info to get that token here:

woodpecker/cli/setup/token_fetcher.go

Line 125 in e5f3e67

return err

A hint in the help where the config file is usually written (e.g. ~/.config/woodpecker/config.json on Linux)
Showing an example configuration JSON in the CLI help, to be able to manually create the config file without running woodpecker-cli setup

Would prefer to avoid manual interaction here as documenting means also supporting it and makes every change a breaking change here. IMO if the other points mentioned are resolved this shouldn't be necessary anymore.

(Re)Generating the config file with woodpecker-cli setup by passing environment variables or parameters

Isn't that already the case if you re-run the setup command?