From b98abd799ba5f9d21fb84a459fd3b26e69509f86 Mon Sep 17 00:00:00 2001 From: Makabeez <155258247+Makabeez@users.noreply.github.com> Date: Thu, 6 Aug 2026 10:28:57 +0200 Subject: [PATCH 1/2] docs: fix three onboarding friction points for Linux/headless installs - quickstart: add Linux binary install one-liner for no-Homebrew/headless environments; the existing section was macOS-first with no path for remote servers or WSL boxes without Homebrew installed - quickstart: correct auth description from "opens a browser window" to device-code flow; headless users need to know codes expire (~2 min) and the URL can be opened on any machine - kh_wallet_info: add Node.js/npx prerequisite; the command shells out to npx @keeperhub/wallet but this dependency was undocumented, causing "could not determine executable to run" with no actionable guidance Found during a fresh Linux/WSL2 onboarding run on v0.13.1 (2026-08-06). --- docs/kh_wallet_info.md | 2 ++ docs/quickstart.md | 16 ++++++++++++++-- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/kh_wallet_info.md b/docs/kh_wallet_info.md index 8ab937f..ae4b6f7 100644 --- a/docs/kh_wallet_info.md +++ b/docs/kh_wallet_info.md @@ -8,6 +8,8 @@ Print subOrgId and walletAddress from ~/.keeperhub/wallet.json. Thin wrapper around `npx @keeperhub/wallet info`. Exits non-zero if the config is missing. +**Prerequisite:** Node.js (v18+) and `npx` must be on your `PATH`. + ``` kh wallet info [flags] ``` diff --git a/docs/quickstart.md b/docs/quickstart.md index 511c9d0..6af572e 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -2,11 +2,23 @@ ## Install -**Homebrew (macOS/Linux):** +**Homebrew (macOS/Linux with Homebrew):** ``` brew install keeperhub/tap/kh ``` +**Linux (no Homebrew / headless):** +```bash +mkdir -p ~/.local/bin +curl -fsSL https://api.github.com/repos/keeperhub/cli/releases/latest \ + | grep browser_download_url \ + | grep linux_amd64.tar.gz \ + | cut -d '"' -f 4 \ + | xargs curl -fsSL \ + | tar -xzf - -C ~/.local/bin kh +``` +Replace `linux_amd64` with `linux_arm64` on ARM. Ensure `~/.local/bin` is on your `PATH`. + **Go install:** ``` go install github.com/keeperhub/cli/cmd/kh@latest @@ -20,7 +32,7 @@ go install github.com/keeperhub/cli/cmd/kh@latest kh auth login ``` -This opens a browser window to authenticate. Your token is stored in the OS keyring. +This uses the **device code flow**: it prints a URL and a short code. Open the URL in any browser (including on a different machine) and enter the code to complete sign-in. On headless or remote boxes the browser will not open automatically — copy the URL from the terminal. Codes expire after roughly two minutes; re-run `kh auth login` if yours expires before you can visit it. Your token is stored in the OS keyring. To authenticate non-interactively (CI/CD), set `KH_API_KEY` instead. From ff40982125edb4d2f2c3715d67534e5dee92ae1a Mon Sep 17 00:00:00 2001 From: Makabeez <155258247+Makabeez@users.noreply.github.com> Date: Fri, 7 Aug 2026 19:14:48 +0200 Subject: [PATCH 2/2] docs: four fixes to onboarding friction (#88 revision) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move Node.js prerequisite from kh_wallet_info.md (generated, wrong place) to cmd/wallet/wallet.go Long so it covers all agentic subcommands at once and regenerates cleanly into kh_wallet.md - Fix two browser-error sources: auth.go Example comment ("via browser" → device code description) and login.go Long (clarify browser does not open automatically; code TTL is 15 minutes, not "roughly two minutes") - Replace unverified install pipe with checksum-verified snippet: downloads checksums.txt alongside the tarball, runs sha256sum --ignore- missing, then extracts; add GitHub API rate-limit note (60 req/hr/IP) - Regenerate docs/kh_auth*.md, docs/kh_wallet*.md, docs/quickstart.md Co-Authored-By: Claude Sonnet 4.6 --- cmd/auth/auth.go | 2 +- cmd/auth/login.go | 4 +++- cmd/wallet/wallet.go | 4 +++- docs/kh_auth.md | 2 +- docs/kh_auth_login.md | 4 +++- docs/kh_wallet.md | 2 ++ docs/kh_wallet_info.md | 2 -- docs/quickstart.md | 15 ++++++++------- 8 files changed, 21 insertions(+), 14 deletions(-) diff --git a/cmd/auth/auth.go b/cmd/auth/auth.go index 2cfef97..5dfbaf9 100644 --- a/cmd/auth/auth.go +++ b/cmd/auth/auth.go @@ -9,7 +9,7 @@ func NewAuthCmd(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "auth", Short: "Authenticate with KeeperHub", - Example: ` # Log in via browser + Example: ` # Log in (device code flow — prints a URL and code to confirm in a browser) kh auth login # Check current auth status diff --git a/cmd/auth/login.go b/cmd/auth/login.go index aa0d4eb..a295de7 100644 --- a/cmd/auth/login.go +++ b/cmd/auth/login.go @@ -52,7 +52,9 @@ func NewLoginCmd(f *cmdutil.Factory) *cobra.Command { Short: "Log in to KeeperHub", Args: cobra.NoArgs, Long: `Authenticate with KeeperHub using the device code flow. -Prints a URL and a one-time code; open the URL in a browser to confirm it. +Prints a URL and a one-time code. Open the URL in any browser (the browser +does not open automatically — copy the URL from the terminal) and enter the +code to complete sign-in. Codes expire after 15 minutes. Use --with-token to read an API key from stdin for non-interactive automation. See also: kh auth status, kh auth logout`, diff --git a/cmd/wallet/wallet.go b/cmd/wallet/wallet.go index 6664f5d..e9a3bc0 100644 --- a/cmd/wallet/wallet.go +++ b/cmd/wallet/wallet.go @@ -21,7 +21,9 @@ Agentic wallet (thin wrappers around npx @keeperhub/wallet): kh w info print agentic subOrgId + walletAddress kh w fund print Coinbase Onramp URL + Tempo deposit address kh w link link agentic wallet to a KeeperHub account (needs KH_SESSION_COOKIE) - kh w feedback submit ERC-8004 feedback for a workflow execution this wallet paid for`, + kh w feedback submit ERC-8004 feedback for a workflow execution this wallet paid for + +Prerequisite for agentic subcommands: Node.js (v18+) and npx must be on your PATH.`, Example: ` # Creator wallet balance (REST): kh w balance diff --git a/docs/kh_auth.md b/docs/kh_auth.md index cd74618..f5401d4 100644 --- a/docs/kh_auth.md +++ b/docs/kh_auth.md @@ -5,7 +5,7 @@ Authenticate with KeeperHub ### Examples ``` - # Log in via browser + # Log in (device code flow — prints a URL and code to confirm in a browser) kh auth login # Check current auth status diff --git a/docs/kh_auth_login.md b/docs/kh_auth_login.md index 166f87c..2a8e7d9 100644 --- a/docs/kh_auth_login.md +++ b/docs/kh_auth_login.md @@ -5,7 +5,9 @@ Log in to KeeperHub ### Synopsis Authenticate with KeeperHub using the device code flow. -Prints a URL and a one-time code; open the URL in a browser to confirm it. +Prints a URL and a one-time code. Open the URL in any browser (the browser +does not open automatically — copy the URL from the terminal) and enter the +code to complete sign-in. Codes expire after 15 minutes. Use --with-token to read an API key from stdin for non-interactive automation. See also: kh auth status, kh auth logout diff --git a/docs/kh_wallet.md b/docs/kh_wallet.md index 61940a8..a002c5c 100644 --- a/docs/kh_wallet.md +++ b/docs/kh_wallet.md @@ -17,6 +17,8 @@ Agentic wallet (thin wrappers around npx @keeperhub/wallet): kh w link link agentic wallet to a KeeperHub account (needs KH_SESSION_COOKIE) kh w feedback submit ERC-8004 feedback for a workflow execution this wallet paid for +Prerequisite for agentic subcommands: Node.js (v18+) and npx must be on your PATH. + ### Examples ``` diff --git a/docs/kh_wallet_info.md b/docs/kh_wallet_info.md index ae4b6f7..8ab937f 100644 --- a/docs/kh_wallet_info.md +++ b/docs/kh_wallet_info.md @@ -8,8 +8,6 @@ Print subOrgId and walletAddress from ~/.keeperhub/wallet.json. Thin wrapper around `npx @keeperhub/wallet info`. Exits non-zero if the config is missing. -**Prerequisite:** Node.js (v18+) and `npx` must be on your `PATH`. - ``` kh wallet info [flags] ``` diff --git a/docs/quickstart.md b/docs/quickstart.md index 6af572e..ae2e416 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -9,15 +9,16 @@ brew install keeperhub/tap/kh **Linux (no Homebrew / headless):** ```bash -mkdir -p ~/.local/bin +mkdir -p ~/.local/bin && cd "$(mktemp -d)" curl -fsSL https://api.github.com/repos/keeperhub/cli/releases/latest \ - | grep browser_download_url \ - | grep linux_amd64.tar.gz \ - | cut -d '"' -f 4 \ - | xargs curl -fsSL \ - | tar -xzf - -C ~/.local/bin kh + | grep browser_download_url | cut -d '"' -f 4 \ + | grep -E 'linux_amd64\.tar\.gz|checksums\.txt' \ + | xargs -n1 curl -fsSLO +sha256sum --ignore-missing -c checksums.txt +tar -xzf kh_*_linux_amd64.tar.gz -C ~/.local/bin kh ``` Replace `linux_amd64` with `linux_arm64` on ARM. Ensure `~/.local/bin` is on your `PATH`. +The unauthenticated GitHub API is rate-limited to 60 requests per hour per IP; if you hit that limit, download directly from [GitHub Releases](https://github.com/keeperhub/cli/releases). **Go install:** ``` @@ -32,7 +33,7 @@ go install github.com/keeperhub/cli/cmd/kh@latest kh auth login ``` -This uses the **device code flow**: it prints a URL and a short code. Open the URL in any browser (including on a different machine) and enter the code to complete sign-in. On headless or remote boxes the browser will not open automatically — copy the URL from the terminal. Codes expire after roughly two minutes; re-run `kh auth login` if yours expires before you can visit it. Your token is stored in the OS keyring. +This uses the **device code flow**: it prints a URL and a short code. Open the URL in any browser (including on a different machine) and enter the code to complete sign-in. On headless or remote boxes the browser will not open automatically — copy the URL from the terminal. Codes expire after 15 minutes; re-run `kh auth login` if yours expires. Your token is stored in the OS keyring. To authenticate non-interactively (CI/CD), set `KH_API_KEY` instead.