feat(cli): shell completion, richer help, safer and scriptable commands

Author: zygintas

.goreleaser.yaml

@@ -7,6 +7,7 @@ before:
     - sh -c 'go run . completion bash > completions/hostinger.bash'
     - sh -c 'go run . completion zsh  > completions/hostinger.zsh'
     - sh -c 'go run . completion fish > completions/hostinger.fish'
+    - go run ./tools/gendocs -man manpages
 
 builds:
   - main: ./main.go
@@ -30,6 +31,7 @@ archives:
   - name_template: "hostinger-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
     files:
       - completions/*
+      - manpages/*
     wrap_in_directory: false
 
 source:
@@ -65,6 +67,7 @@ brews:
       bash_completion.install "completions/hostinger.bash" => "hostinger"
       zsh_completion.install  "completions/hostinger.zsh"  => "_hostinger"
       fish_completion.install "completions/hostinger.fish"
+      man1.install Dir["manpages/*.1"]
 
 changelog:
   disable: false

AUTOCOMPLETE.md

@@ -10,6 +10,22 @@ Auto-completion can be generated for multiple shells. The currently supported sh
 - fish
 - PowerShell
 
+Completion covers commands, flag values with a fixed set of choices (`--format`, enum flags) and IDs:
+where a command takes the ID or name of an existing resource, `<TAB>` lists yours (with a name or
+hostname next to each), fetched from the API with your configured credentials. Results are cached for
+two minutes, and completion never opens a browser sign-in.
+
+## Quick setup
+
+```bash
+hostinger completion install          # detects the shell from $SHELL
+hostinger completion install zsh      # or name it: bash, zsh, fish, powershell
+```
+
+It writes the script where the shell loads it from and prints any one-time setup step still needed.
+Run it again after upgrading to pick up new commands. Homebrew installs already include completions.
+The sections below set it up by hand instead.
+
 After adding shell auto-completion, remember to refresh your shell profile by logging out from the shell and log back in.
 
 ## Bash

README.md

@@ -16,25 +16,36 @@
 brew install hostinger/tap/hostinger
 ```
 
-Upgrade with `brew upgrade hostinger`. Shell tab-completion (bash/zsh/fish) is installed
-automatically.
+Upgrade with `brew upgrade hostinger`. Shell tab-completion (bash/zsh/fish) and man pages
+(`man hostinger`) are installed automatically.
 
 ### Binary download
 
 Download the binary for your platform from the
-[releases page](https://github.com/hostinger/api-cli/releases).
+[releases page](https://github.com/hostinger/api-cli/releases). Then enable tab-completion
+with `hostinger completion install` (see [AUTOCOMPLETE.md](AUTOCOMPLETE.md)).
 
 ## Configuration
 
-Create `$HOME/.hostinger.yaml`:
+Sign in through the browser:
+
+```sh
+hostinger auth login
+```
+
+or use an API token instead: run `hostinger config set api_token` (it asks for the token
+without echoing it) or set the `HOSTINGER_API_TOKEN` environment variable. A token takes precedence over
+the sign-in. Generate one at [hPanel → API](https://hpanel.hostinger.com/profile/api).
+
+`hostinger auth status` shows which credentials are in use. Settings live in
+`$HOME/.hostinger.yaml` (`hostinger config list` shows them):
 
 ```yaml
 api_token: <your API token>
+format: json        # default output format
+no_input: false     # true: never prompt
 ```
 
-or set the `HOSTINGER_API_TOKEN` environment variable. Generate a token at
-[hPanel → API](https://hpanel.hostinger.com/profile/api).
-
 ## Usage
 
 ```
@@ -50,7 +61,36 @@ hostinger vps vm start 123          # vm is an alias for virtual-machines
 hostinger dns records list example.com
 ```
 
-Output format defaults to a table; use `--format json|table|tree` to change it.
-Command documentation lives in [docs/](docs/), and `manifest.json` maps every
-API operation to its command. Shell autocompletion: see
-[AUTOCOMPLETE.md](AUTOCOMPLETE.md).
+Every command's `--help` lists its required flags separately and shows examples. Flags that take
+JSON accept inline JSON, `@file.json`, or `-` for stdin; the help shows the expected shape.
+
+### Output
+
+- Tables on a terminal, JSON when the output is piped or redirected. Choose explicitly with
+  `-o/--format table|json|yaml|tree`, or set a default with `hostinger config set format json`.
+- `--jq '<expr>'` filters the JSON response (strings print raw), e.g. `--jq '.[].id'`.
+- List commands with pages take `--all` to fetch every page.
+
+### Prompts and safety
+
+- In a terminal, missing arguments and required flags are asked for, with choices listed where
+  they are known. `--no-input` (or `no_input: true`) turns prompting off.
+- Commands that delete, stop, restore or purchase ask for confirmation. Pass `--yes` to skip it;
+  non-interactive runs (scripts, CI) must pass `--yes`.
+- `--dry-run` prints the request as a `curl` command instead of sending it.
+- Commands that start an asynchronous action take `--wait` to block until it finishes.
+- `--verbose` prints each HTTP request and its status to stderr.
+
+### Exit codes
+
+| Code | Meaning                                       |
+|------|-----------------------------------------------|
+| 0    | Success                                       |
+| 1    | API, network or other error; aborted prompt   |
+| 2    | Invalid arguments, flags or input             |
+| 3    | No credentials, or authentication failed (HTTP 401/403) |
+| 4    | Not found (HTTP 404)                          |
+| 5    | Validation failed (HTTP 422)                  |
+
+Command documentation lives in [docs/](docs/) and in the man pages, and `manifest.json` maps every
+API operation to its command. Shell autocompletion: see [AUTOCOMPLETE.md](AUTOCOMPLETE.md).

api/oauth.go

@@ -138,6 +138,54 @@ func (s *OAuthService) Token(ctx context.Context) (string, error) {
 	return s.resolve(ctx)
 }
 
+// ErrNotSignedIn is returned by TokenNoLogin when only an interactive sign-in
+// could produce a token.
+var ErrNotSignedIn = errors.New("not signed in")
+
+// TokenNoLogin is Token without the interactive fallback: the cached token, or
+// a refresh, or ErrNotSignedIn. Shell completion uses it so a TAB press never
+// opens a browser.
+func (s *OAuthService) TokenNoLogin(ctx context.Context) (string, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	creds, _ := s.loadCredentials()
+	if creds.AccessToken != "" && creds.ExpiresAt != 0 && nowMillis() < creds.ExpiresAt {
+		return creds.AccessToken, nil
+	}
+	if creds.RefreshToken == "" || creds.ClientID == "" {
+		return "", ErrNotSignedIn
+	}
+	return s.refresh(ctx, creds)
+}
+
+// Status describes the stored sign-in without touching the network.
+type Status struct {
+	SignedIn   bool      // an access or refresh token is stored
+	Expired    bool      // the access token has expired (a refresh may still work)
+	CanRefresh bool      // a refresh token is stored
+	ExpiresAt  time.Time // access token expiry; zero when unknown
+	CredPath   string
+}
+
+// Status reports the stored sign-in state.
+func (s *OAuthService) Status() Status {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	creds, _ := s.loadCredentials()
+	st := Status{
+		SignedIn:   creds.AccessToken != "" || creds.RefreshToken != "",
+		CanRefresh: creds.RefreshToken != "" && creds.ClientID != "",
+		CredPath:   s.credPath,
+	}
+	if creds.ExpiresAt != 0 {
+		st.ExpiresAt = time.UnixMilli(creds.ExpiresAt)
+		st.Expired = nowMillis() >= creds.ExpiresAt
+	}
+	return st
+}
+
 // Login runs the full interactive PKCE flow regardless of cache state.
 func (s *OAuthService) Login(ctx context.Context) (string, error) {
 	s.mu.Lock()

api/request.go

@@ -11,7 +11,20 @@ import (
 	"net/http"
 )
 
+// Request returns the API client for a command run. Without a static token it
+// signs in through OAuth, opening the browser when needed.
 func Request() client.ClientWithResponsesInterface {
+	return newClient(true)
+}
+
+// CompletionRequest returns an API client for shell completion: it uses the
+// static token or an already stored OAuth sign-in, and never starts an
+// interactive login.
+func CompletionRequest() client.ClientWithResponsesInterface {
+	return newClient(false)
+}
+
+func newClient(interactive bool) client.ClientWithResponsesInterface {
 	apiURL := viper.GetString("api_url")
 	if apiURL == "" {
 		apiURL = "https://developers.hostinger.com"
@@ -21,14 +34,22 @@ func Request() client.ClientWithResponsesInterface {
 		client.WithRequestEditorFn(addUserAgent),
 	}
 
-	if staticToken := viper.GetString("api_token"); staticToken != "" {
+	var doer client.HttpRequestDoer = &http.Client{}
+	if viper.GetBool("verbose") {
+		doer = &verboseDoer{base: doer}
+	}
+
+	if interactive && viper.GetBool("dry_run") {
+		// Print the request instead of sending it; no credentials are needed.
+		opts = append(opts, client.WithHTTPClient(&dryRunDoer{}))
+	} else if staticToken := viper.GetString("api_token"); staticToken != "" {
 		// Static token wins: use it unchanged. OAuth and 401 re-auth are skipped
 		// because there is no refresh source for a user-managed token.
 		bearer, err := securityprovider.NewSecurityProviderBearerToken(staticToken)
 		if err != nil {
 			panic(err)
 		}
-		opts = append(opts, client.WithRequestEditorFn(bearer.Intercept))
+		opts = append(opts, client.WithRequestEditorFn(bearer.Intercept), client.WithHTTPClient(doer))
 	} else {
 		// No static token: obtain the bearer via the OAuth service, and retry
 		// once on a 401 after forcing a fresh token.
@@ -37,8 +58,8 @@ func Request() client.ClientWithResponsesInterface {
 			log.Fatal(err)
 		}
 		opts = append(opts,
-			client.WithRequestEditorFn(oauthBearer(oauth)),
-			client.WithHTTPClient(&oauthRetryDoer{oauth: oauth, base: &http.Client{}}),
+			client.WithRequestEditorFn(oauthBearer(oauth, interactive)),
+			client.WithHTTPClient(&oauthRetryDoer{oauth: oauth, base: doer, interactive: interactive}),
 		)
 	}
 
@@ -51,10 +72,15 @@ func Request() client.ClientWithResponsesInterface {
 }
 
 // oauthBearer resolves a token (cached -> refresh -> interactive login) and
-// attaches it as the Authorization header before each request is sent.
-func oauthBearer(oauth *OAuthService) client.RequestEditorFn {
+// attaches it as the Authorization header before each request is sent. When
+// interactive is false the login step is skipped.
+func oauthBearer(oauth *OAuthService, interactive bool) client.RequestEditorFn {
 	return func(ctx context.Context, req *http.Request) error {
-		token, err := oauth.Token(ctx)
+		resolve := oauth.Token
+		if !interactive {
+			resolve = oauth.TokenNoLogin
+		}
+		token, err := resolve(ctx)
 		if err != nil {
 			return err
 		}
@@ -65,15 +91,17 @@ func oauthBearer(oauth *OAuthService) client.RequestEditorFn {
 
 // oauthRetryDoer performs API requests and, on a 401, forces a fresh token via
 // Reauthenticate and retries the request exactly once (spec §8). A second 401
-// is returned to the caller unchanged — it never loops.
+// is returned to the caller unchanged — it never loops. Non-interactive
+// clients return the first 401 as is.
 type oauthRetryDoer struct {
-	oauth *OAuthService
-	base  client.HttpRequestDoer
+	oauth       *OAuthService
+	base        client.HttpRequestDoer
+	interactive bool
 }
 
 func (d *oauthRetryDoer) Do(req *http.Request) (*http.Response, error) {
 	resp, err := d.base.Do(req)
-	if err != nil || resp.StatusCode != http.StatusUnauthorized {
+	if err != nil || resp.StatusCode != http.StatusUnauthorized || !d.interactive {
 		return resp, err
 	}
 

api/transport.go

@@ -0,0 +1,85 @@
+package api
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/hostinger/api-cli/client"
+	"github.com/hostinger/api-cli/utils"
+)
+
+// Streams for --dry-run (the command's output) and --verbose (diagnostics);
+// package vars for tests. nil means os.Stdout / os.Stderr at write time.
+var (
+	dryRunOut  io.Writer
+	verboseOut io.Writer
+)
+
+func writerOr(w, fallback io.Writer) io.Writer {
+	if w != nil {
+		return w
+	}
+	return fallback
+}
+
+// dryRunDoer prints each request as an equivalent curl command and returns
+// utils.ErrDryRun instead of sending it. The token is written as an
+// environment variable reference, never its value.
+type dryRunDoer struct{}
+
+func (dryRunDoer) Do(req *http.Request) (*http.Response, error) {
+	var b strings.Builder
+	fmt.Fprintf(&b, "curl -X %s %s", req.Method, shellQuote(req.URL.String()))
+	fmt.Fprintf(&b, " \\\n  -H \"Authorization: Bearer $%sAPI_TOKEN\"", utils.EnvPrefix)
+	if ct := req.Header.Get("Content-Type"); ct != "" {
+		fmt.Fprintf(&b, " \\\n  -H %s", shellQuote("Content-Type: "+ct))
+	}
+	if req.Body != nil && req.Body != http.NoBody {
+		body, err := io.ReadAll(req.Body)
+		if err != nil {
+			return nil, err
+		}
+		if len(body) > 0 {
+			fmt.Fprintf(&b, " \\\n  -d %s", shellQuote(string(body)))
+		}
+	}
+	fmt.Fprintln(writerOr(dryRunOut, os.Stdout), b.String())
+	return nil, utils.ErrDryRun
+}
+
+// noTokenDoer fails every request of a build without OAuth when no API token
+// is configured.
+type noTokenDoer struct{}
+
+func (noTokenDoer) Do(*http.Request) (*http.Response, error) {
+	return nil, fmt.Errorf("%w: set %sAPI_TOKEN or run '%s config set api_token'",
+		utils.ErrNoCredentials, utils.EnvPrefix, filepath.Base(os.Args[0]))
+}
+
+// verboseDoer logs each request line and the response status with timing to
+// stderr. Headers are not logged, so credentials never reach the log.
+type verboseDoer struct {
+	base client.HttpRequestDoer
+}
+
+func (d *verboseDoer) Do(req *http.Request) (*http.Response, error) {
+	fmt.Fprintf(writerOr(verboseOut, os.Stderr), "> %s %s\n", req.Method, req.URL.String())
+	start := time.Now()
+	resp, err := d.base.Do(req)
+	elapsed := time.Since(start).Round(time.Millisecond)
+	if err != nil {
+		fmt.Fprintf(writerOr(verboseOut, os.Stderr), "< error after %s: %v\n", elapsed, err)
+		return resp, err
+	}
+	fmt.Fprintf(writerOr(verboseOut, os.Stderr), "< %s (%s)\n", resp.Status, elapsed)
+	return resp, nil
+}
+
+func shellQuote(s string) string {
+	return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'"
+}