Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
HEE-TOOLS-UPDATE(1)                HEE Tools                HEE-TOOLS-UPDATE(1)

NAME
       hee-tools-update - install or refresh the pinned external toolchain

SYNOPSIS
              hee-tools-update [--force|--reinstall] [MANIFEST] [LOG_DIR]
              hee-tools-update help

DESCRIPTION
              Walks the toolchain manifest and acts on each entry according to its
              `kind` column. This tool WRITES to the filesystem and DOWNLOADS from
              the network -- it is the mutating half of the pair; hee-tools-check is
              the read-only half.

              MANIFEST defaults to tooling/tools.manifest.txt resolved relative to
              this script, so it works from any directory.

              LOG_DIR defaults to $XDG_STATE_HOME/hee/tools (that is
              ~/.local/state/hee/tools unless XDG_STATE_HOME is set). A run log
              records what got installed on THIS machine at one moment -- host
              state, not repo content -- and XDG_STATE_HOME is the directory the
              spec reserves for exactly that.

              It used to default to the RELATIVE path hee/evidence/tools, which
              landed the log wherever you happened to be standing. Run from a repo
              root -- the documented way -- that dirtied the worktree, and
              ci/git/hee-preflight.sh is a hard gate that refuses a dirty worktree.
              So a SUCCESSFUL toolchain update blocked the next session's entry
              until someone cleaned up after it. Real, and it happened
              (issue:501@human-execution-engine).

              Pass LOG_DIR explicitly if you do want the log inside a repo.

              Manifest lines are `name kind desired`. Blank lines and # comments are
              skipped. Handled kinds, and only these:

                go tar <version>    compares `go version` against <version> and, only if
                                    they differ (or go is absent, or --force), downloads
                                    https://go.dev/dl/go<version>.linux-amd64.tar.gz, records
                                    its sha256 in the log, wipes and re-extracts
                                    $HOME/.local/go/<version>, then symlinks go and gofmt
                                    into $HOME/.local/bin. The short-circuit was added
                                    because the unconditional reinstall re-downloaded ~150MB
                                    every run and re-triggered a `curl (23)` write failure on
                                    disk-constrained hosts (issue:826@human-execution-engine).
                yq bin <version>    compares `yq --version` against <version> and, only if
                                    they differ (or yq is absent, or --force), downloads the
                                    mikefarah/yq linux_amd64 release binary and moves it
                                    into $HOME/.local/bin/yq (via a temp file, so a failed
                                    download never leaves a truncated yq on PATH ahead of
                                    the distro's Python yq).
                <name> pkg <any>    reports presence only and prints an apt hint. NEVER
                                    installs anything. Recognized for jq, bat, glow, rg
                                    and tmux by name; any other name:kind pair is logged
                                    as an unknown manifest entry and skipped.

              A FAILED download does not abort the run. Each downloading kind guards its
              own download and returns cleanly on failure; the loop records the severity
              from the line's requiredness (`req`, the 5th manifest column -- absent means
              required) and moves on to the next line. So a broken OPTIONAL entry -- the go
              tarball is optional -- can no longer block a REQUIRED one that follows it,
              such as yq. Before this, a `curl (23)` write error on the go download aborted
              the whole run under `set -e` and yq was never reached.

              Architecture is hardcoded linux/amd64 for both downloading kinds. On
              any other OS or architecture this tool will fetch the wrong artifact
              rather than refuse -- a real limitation, not a documented option.

              Real footgun: every line of output goes to the log file only. `log()`
              pipes through `tee -a "$OUT" >/dev/null`, and the downloads are quiet
              (curl -fsSL), so a successful run prints NOTHING to the terminal. Read
              LOG_DIR/tools-update.<UTC-timestamp>.log to see what happened. The
              resolved path is printed when the run starts.

OPTIONS
              --force, --reinstall   Reinstall every downloading kind (go, yq) even when it
                                     is already at the pinned version, bypassing the version
                                     short-circuit. The escape hatch for a corrupt install
                                     whose version string still matches. Must be the FIRST
                                     argument (a leading-flag test keeps spaces in MANIFEST/
                                     LOG_DIR intact).

ENVIRONMENT
              HOME               install prefix -- $HOME/.local/bin and $HOME/.local/go
              TMPDIR             download scratch space for the go tarball (default /tmp)
              PATH               must contain $HOME/.local/bin for the installed
                                 binaries to be reachable; the log says so if it is not
              HEE_STATUS_STYLE   icon (default), ascii, or plain. See heerc.

FILES
              tooling/tools.manifest.txt              default manifest
              $XDG_STATE_HOME/hee/tools/tools-update.*.log   per-run log

EXIT STATUS
              Nagios plugin convention; the worst line wins, matching hee-tools-check.
              0 OK        every manifest line was processed and every install succeeded
              1 WARNING   an OPTIONAL line's install failed (bad download/extract). Other
                          lines still ran.
              2 CRITICAL  a REQUIRED line's install failed, or a line names a kind this
                          tool cannot act on (that line was skipped, so a pin is unapplied).

              A failed download no longer aborts the run or leaks curl's own exit code:
              the download is guarded, the failure is mapped to WARNING/CRITICAL by the
              line's requiredness, and the remaining lines are still processed.

EXAMPLES
              hee tools-update

              hee tools-update --force

              Neither is marked "# ci": both download and install the pinned toolchain (go,
              yq) into ~/.local, a mutation of the host, so there is no read-only run to
              prove. --force reinstalls even when the version already matches. hee
              tools-check is the read-only half and IS proven in CI.

SEE ALSO
              hee-tools, hee-tools-check

                                                            HEE-TOOLS-UPDATE(1)