setup-cli

What this skill does

Creates three wrapper scripts in ~/.local/bin/ that exec into the latest installed fleet plugin's bin/ dir. After running this once, the user can invoke claude-sessions, claude-sessions-web, and spawn-claude-feature directly from their terminal — and a future /plugin update fleet@bytedesk won't break them.

Why this is needed

Claude Code injects ${CLAUDE_PLUGIN_ROOT}/bin/ into the tool host's PATH, so skills that shell out to claude-sessions work. It does not inject that path into the user's interactive zsh / bash, so claude-sessions attach <TICKET> from a terminal returns command not found. v1.0.0 (BDM-3) intentionally removed the old ~/.local/bin/ symlinks — this skill fills the gap that left without re-introducing version-pinned symlinks.

Why a wrapper, not a symlink

A symlink would point at one specific installed version (e.g. 1.7.0/bin/claude-sessions) and break the moment /plugin update installed 1.8.0 and removed the older copy. The wrapper resolves the latest version path each call:

exec "$(ls -dv ~/.claude/plugins/cache/bytedesk/fleet/*/bin/<NAME> 2>/dev/null | tail -1)" "$@"

ls -dv … | tail -1 gives the highest version-sorted directory, so updates are transparent.

Steps

Run the bash block below verbatim. It is idempotent and reports per-wrapper status. Read the output back to the user.

set -u
target_dir="$HOME/.local/bin"
sentinel='# fleet-setup-cli-wrapper'
binaries=(claude-sessions claude-sessions-web spawn-claude-feature)
mkdir -p "$target_dir"

created=()
refreshed=()
foreign=()

for name in "${binaries[@]}"; do
  dest="$target_dir/$name"
  template=$(cat <<EOF
#!/usr/bin/env bash
$sentinel
# Auto-generated by /fleet:setup-cli — resolves to the latest installed
# bytedesk fleet plugin version, so /plugin update does not break the
# user-facing CLI. Safe to overwrite by re-running /fleet:setup-cli.
exec "\$(ls -dv ~/.claude/plugins/cache/bytedesk/fleet/*/bin/$name 2>/dev/null | tail -1)" "\$@"
EOF
  )

  if [ -e "$dest" ] || [ -L "$dest" ]; then
    if [ -f "$dest" ] && grep -qF "$sentinel" "$dest" 2>/dev/null; then
      printf '%s\n' "$template" > "$dest"
      chmod +x "$dest"
      refreshed+=("$dest")
    else
      foreign+=("$dest")
    fi
  else
    printf '%s\n' "$template" > "$dest"
    chmod +x "$dest"
    created+=("$dest")
  fi
done

echo "fleet:setup-cli summary"
echo "  target dir : $target_dir"
echo "  created    : ${#created[@]}${created:+ — ${created[*]}}"
echo "  refreshed  : ${#refreshed[@]}${refreshed:+ — ${refreshed[*]}}"
echo "  skipped    : ${#foreign[@]}${foreign:+ — ${foreign[*]} (foreign file at path; not overwritten)}"
echo
echo "PATH check:"
which claude-sessions || echo "  (claude-sessions not on PATH — is $target_dir on \$PATH?)"

Edge cases

• ~/.local/bin does not exist. Created via mkdir -p. No error.
• Wrapper already exists at the target path. If the file contains the # fleet-setup-cli-wrapper sentinel, it is overwritten with the current template (idempotent refresh). If the sentinel is absent, the path is reported under skipped and left alone — never silently clobber a user's own script.
• Symlink at the target path. Treated like a foreign file (sentinel grep on a non-text symlink target won't match). Reported as skipped.
• Plugin not yet installed / installed at a different path. The wrapper is still written; it will fail at exec time with a clear shell error from exec "". That is the documented "fail loudly when uninstalled" behaviour from the ticket.
• ~/.local/bin not on the user's PATH. The which claude-sessions line at the end will fail and print a hint. The user fixes their shell rc; this skill does not edit shell rc files.

Reporting back

Always end with the which claude-sessions output so the user can see whether the wrapper is actually being picked up by their shell. If which returns the wrapper path, success. If it falls back to a different location or "not found", report that explicitly so the user knows to check their $PATH.

If any wrappers were skipped because of foreign files at the target path, list each one and tell the user to inspect / move / delete them manually before re-running the skill.

Constraints

• Only writes to ~/.local/bin/. Never edits shell rc files (.zshrc, .bashrc, .profile).
• Never deletes anything.
• Never overwrites a file at the target path that is not already a wrapper this skill created (sentinel-gated).
• Re-running is safe — refresh is the expected normal path after an update changes the wrapper template.

Examples

/fleet:setup-cli