From 971efcdafe0b0c50e5c8a43ed2c470b92746e06e Mon Sep 17 00:00:00 2001
From: Paulius Krutkis <paulius.krutkis@decodo.com>
Date: Tue, 30 Jun 2026 15:30:10 +0300
Subject: [PATCH 1/2] Make non-root install land decodo on PATH without the
 full path

The user-level fallback installed to a bespoke ~/.npm-global that is on
nobody's PATH, so a non-root user had to invoke the absolute path to the
binary. Match the uv/pipx experience:

- Install the fallback to the XDG-standard ~/.local (binary in ~/.local/bin),
  which is commonly already on PATH.
- When the install dir is not on PATH, symlink decodo into the first writable
  directory already on PATH so it is runnable by name immediately.
- Always print the short `decodo` command in next-steps and setup guidance
  instead of the absolute path; show a restart/rehash hint when needed.

install.ps1 mirrors the presentation change (always show `decodo`).
---
 docs/install.ps1 |  4 ---
 docs/install.sh  | 80 +++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 72 insertions(+), 12 deletions(-)

diff --git a/docs/install.ps1 b/docs/install.ps1
index e0651ec..95aaf72 100644
--- a/docs/install.ps1
+++ b/docs/install.ps1
@@ -125,10 +125,6 @@ function Get-DecodoBin([string]$BinDir) {
 }
 
 function Get-CommandPrefix([string]$BinDir) {
-  if ($script:PathActivationRequired) {
-    return Get-DecodoBin $BinDir
-  }
-
   return $CommandName
 }
 
diff --git a/docs/install.sh b/docs/install.sh
index e178995..b404f2b 100755
--- a/docs/install.sh
+++ b/docs/install.sh
@@ -9,6 +9,7 @@ ORIG_PATH=""
 USER_PREFIX_BIN=""
 PATH_ACTIVATION_REQUIRED=0
 ACTIVATION_RC_FILE=""
+LINKED_DIR=""
 
 if [ -t 1 ]; then
   RED='\033[0;31m'
@@ -83,13 +84,73 @@ ensure_path() {
   warn "$dir was not in your PATH. Added it to $rc_file"
 }
 
-command_prefix() {
+first_writable_path_dir() {
+  exclude="$1"
+  old_ifs="$IFS"
+  IFS=:
+  set -f
+  set -- $ORIG_PATH
+  set +f
+  IFS="$old_ifs"
+
+  for dir in "$@"; do
+    [ -n "$dir" ] || continue
+    case "$dir" in
+      /*) ;;
+      *) continue ;;
+    esac
+    [ "$dir" = "$exclude" ] && continue
+    if [ -d "$dir" ] && [ -w "$dir" ]; then
+      printf '%s' "$dir"
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+link_command() {
   bin_dir="$1"
-  if [ "$PATH_ACTIVATION_REQUIRED" = 1 ]; then
-    printf '%s/%s' "$bin_dir" "$COMMAND_NAME"
-  else
-    printf '%s' "$COMMAND_NAME"
+  dest_dir="$2"
+  src="${bin_dir}/${COMMAND_NAME}"
+  dest="${dest_dir}/${COMMAND_NAME}"
+
+  [ -e "$src" ] || return 1
+  if [ -e "$dest" ] && [ ! -L "$dest" ]; then
+    return 1
   fi
+
+  ln -sf "$src" "$dest" 2>/dev/null || return 1
+  return 0
+}
+
+link_command_onto_path() {
+  bin_dir="$1"
+
+  if path_contains "$bin_dir" "$ORIG_PATH"; then
+    return 0
+  fi
+
+  link_dir=$(first_writable_path_dir "$bin_dir") || link_dir=""
+  if [ -n "$link_dir" ] && link_command "$bin_dir" "$link_dir"; then
+    LINKED_DIR="$link_dir"
+    return 0
+  fi
+
+  ensure_path "$bin_dir"
+}
+
+print_rehash_hint() {
+  shell_name=$(basename "${SHELL:-/bin/sh}")
+  case "$shell_name" in
+    zsh | bash)
+      printf "${DIM}If this shell can't find decodo yet, run: hash -r${RESET}\n"
+      ;;
+  esac
+}
+
+command_prefix() {
+  printf '%s' "$COMMAND_NAME"
 }
 
 print_activation_steps() {
@@ -197,10 +258,10 @@ install_package() {
     warn "Global install failed. Falling back to a user-level install."
   else
     warn "No write permission for the npm global directory ($(npm prefix -g 2>/dev/null))."
-    info "Installing ${PACKAGE_NAME} to ${HOME}/.npm-global instead (no sudo needed)..."
   fi
 
-  user_prefix="${HOME}/.npm-global"
+  user_prefix="${HOME}/.local"
+  info "Installing ${PACKAGE_NAME} to ${user_prefix} (no sudo needed)..."
   mkdir -p "$user_prefix"
 
   if ! npm install -g --prefix "$user_prefix" "${PACKAGE_NAME}"; then
@@ -230,7 +291,7 @@ main() {
   install_package
 
   BIN_DIR=$(resolve_install_bin)
-  ensure_path "$BIN_DIR"
+  link_command_onto_path "$BIN_DIR"
 
   installed_version=$("${BIN_DIR}/${COMMAND_NAME}" --version 2>/dev/null || echo "unknown")
   printf '\n'
@@ -238,6 +299,9 @@ main() {
 
   if [ "$PATH_ACTIVATION_REQUIRED" = 1 ]; then
     print_activation_steps "$BIN_DIR"
+  elif [ -n "$LINKED_DIR" ]; then
+    success "Ready to use — decodo is on your PATH (linked into ${LINKED_DIR})."
+    print_rehash_hint
   else
     success "Ready to use — decodo is on your PATH."
   fi

From 54b5097d9dac494331b319ecddf7b637721cb7f0 Mon Sep 17 00:00:00 2001
From: Paulius Krutkis <paulius.krutkis@decodo.com>
Date: Tue, 30 Jun 2026 15:37:57 +0300
Subject: [PATCH 2/2] Bump version to 1.0.2 in package.json for minor updates

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 9ae3823..bea7b15 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@decodo/cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Official CLI for the Decodo APIs",
   "license": "MIT",
   "type": "module",