@hardfin/cli 0.1.0-dev.23 → 0.1.0-dev.25

package/README.md

@@ -224,13 +224,37 @@ environment, so `hardfin login` works out of the box.
 ## Completing commands in your shell
 
 ```sh
-source <(hardfin completion zsh)     # this shell, now
-hardfin completion zsh >> ~/.zshrc   # every shell after this one
+hardfin completion install   # every shell after this one
 ```
 
-`bash`, `zsh`, `fish` and `powershell` each get a script. The script asks the CLI what may
-follow what you have typed, so completions never fall behind the commands, including the ones
-generated from the API document.
+`install` finds your shell from `$SHELL`, shows what it will change, and asks before changing
+it. Name the shell to install for another one, and pass `--yes` to skip the question.
+
+| Shell      | The script is written to                  | And loaded from                            |
+| ---------- | ----------------------------------------- | ------------------------------------------ |
+| bash       | `~/.local/share/hardfin/completion.bash`  | `~/.bashrc`, or `~/.bash_profile` on macOS |
+| zsh        | `~/.local/share/hardfin/completion.zsh`   | `~/.zshrc`                                 |
+| fish       | `~/.config/fish/completions/hardfin.fish` | fish, by itself                            |
+| PowerShell | `~/.local/share/hardfin/completion.ps1`   | the profile PowerShell reports             |
+
+The lines added to a startup file sit between `# >>> hardfin completion >>>` and
+`# <<< hardfin completion <<<`. Installing again replaces them, and
+`hardfin completion uninstall` removes them with the script. Install again after upgrading, so
+the script matches the CLI.
+
+To complete in the current shell without installing anything:
+
+```sh
+source <(hardfin completion zsh)
+```
+
+The script asks the CLI what may follow what you have typed, so completions never fall behind
+the commands, including the ones generated from the API document. It offers commands, flags,
+the values a flag accepts, and file paths where a flag takes one. zsh, fish and PowerShell
+show a description beside each.
+
+The script calls `hardfin` by name, so it needs `hardfin` on your `PATH`. Running
+`node dist/cli.js` from a checkout leaves nothing for it to call, and `npm link` fixes that.
 
 ## Serving an agent
 
@@ -354,7 +378,7 @@ npm run check-types      # tsc
 npm run lint             # eslint, with type-aware rules
 npm run prettier:write   # formatting
 npm test                 # vitest
-npm run build            # tsdown, into dist/cli.js
+npm run build            # tsdown, into dist/, then the completion tree
 ```
 
 CI runs all five on every pull request, plus a check that the generated commands still match