fix(cli): installers show the skill hint only for a binary that has install skills

The released v1 binary has no install skills command, so the stable
installer would point agents at a missing command until the next Dify
release ships v2. The hint now asks the installed binary first and stays
quiet when it fails.

Author: GareArc

cli/scripts/install-cli.sh

@@ -28,7 +28,9 @@ err() { printf '%s\n' "install-cli: $*" >&2; }
 die() { err "$*"; rm -f "$FETCH_ERR_FILE"; exit 1; }
 need() { command -v "$1" >/dev/null 2>&1 || die "$1 is required"; }
 re_escape() { printf '%s' "$1" | sed 's/[][\\.^$*+?(){}|/]/\\&/g'; }
+# print_skill_hint BIN: the hint names a v2 command, so a binary without it (any v1 build) gets none.
 print_skill_hint() {
+  "$1" install skills --help >/dev/null 2>&1 || return 0
   printf '%s\n' 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'
 }
 
@@ -248,7 +250,7 @@ main() {
     case ":${PATH}:" in
         *":${bin_dir}:"*)
             printf 'verify: run "difyctl version"\n'
-            print_skill_hint
+            print_skill_hint "$target_bin"
             ;;
         *)
             printf '\n%s is not on your PATH. Add this to your shell profile:\n' "$bin_dir"

cli/scripts/install-cli.test.ts

@@ -471,3 +471,31 @@ describe('install-cli.sh install_binary', () => {
     expect(r.stderr).toMatch(/cannot write \/nonexistent-dir\/difyctl/)
   })
 })
+
+// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".
+describe.skipIf(process.platform === 'win32')('install-cli.sh print_skill_hint', () => {
+  const fakeBins = [
+    'd="$(mktemp -d)"',
+    'printf \'#!/bin/sh\\n[ "$*" = "install skills --help" ]\\n\' > "$d/v2"',
+    'printf \'#!/bin/sh\\necho "unknown command: $*" >&2\\nexit 1\\n\' > "$d/v1"',
+    'chmod 0755 "$d/v2" "$d/v1"',
+  ]
+
+  it('prints the hint for a binary that has install skills', () => {
+    const r = runLib([...fakeBins, 'print_skill_hint "$d/v2"', 'rm -rf "$d"'].join('\n'))
+    expect(r.code).toBe(0)
+    expect(r.stdout).toMatch(/difyctl install skills <skills root>/)
+  })
+
+  it('prints nothing for a binary without install skills', () => {
+    const r = runLib([...fakeBins, 'print_skill_hint "$d/v1"', 'rm -rf "$d"'].join('\n'))
+    expect(r.code).toBe(0)
+    expect(r.stdout).toBe('')
+  })
+
+  it('prints nothing when the binary cannot run', () => {
+    const r = runLib('print_skill_hint /nonexistent/difyctl')
+    expect(r.code).toBe(0)
+    expect(r.stdout).toBe('')
+  })
+})

cli/scripts/install-r2.ps1

@@ -51,7 +51,11 @@ function Get-PathHint([string]$Dir) {
   return "  [Environment]::SetEnvironmentVariable('PATH', `"$Dir;`" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')"
 }
 
-function Write-SkillHint {
+# The hint names a v2 command, so a binary without it (any v1 build) gets none. Under
+# Windows PowerShell 5.1 a redirected stderr line throws when errors stop, hence the catch.
+function Write-SkillHint([string]$Bin) {
+  try { & $Bin install skills --help *> $null } catch { return }
+  if ($LASTEXITCODE -ne 0) { return }
   Write-Host 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'
 }
 
@@ -79,7 +83,7 @@ function Install-DifyctlBinary([string]$dlUrl, [string]$sha, [string]$version, [
     Write-Host (Get-PathHint $installDir)
   }
   else {
-    Write-SkillHint
+    Write-SkillHint $dest
   }
 }
 

cli/scripts/install-r2.ps1.test.ts

@@ -1,4 +1,6 @@
 import { spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vite-plus/test'
@@ -106,3 +108,30 @@ d('install-r2.ps1 install location, PATH hint and download', () => {
     expect(r.stdout).toMatch(/checksum mismatch/)
   })
 })
+
+// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".
+// The fakes are shell scripts, so this runs where pwsh runs outside Windows.
+describe.skipIf(!hasPwsh || process.platform === 'win32')('install-r2.ps1 Write-SkillHint', () => {
+  const hint = (bin: string) => pwsh(`Write-SkillHint '${bin}'`)
+
+  it('prints the hint for a binary that has install skills, and stays quiet otherwise', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'difyctl-hint-'))
+    try {
+      const v2 = join(dir, 'v2')
+      const v1 = join(dir, 'v1')
+      writeFileSync(v2, '#!/bin/sh\n[ "$*" = "install skills --help" ]\n', { mode: 0o755 })
+      writeFileSync(v1, '#!/bin/sh\necho "unknown command: $*" >&2\nexit 1\n', { mode: 0o755 })
+      expect(hint(v2)).toMatchObject({
+        code: 0,
+        stdout: expect.stringContaining('difyctl install skills <skills root>'),
+      })
+      expect(hint(v1)).toMatchObject({ code: 0, stdout: '' })
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('prints nothing when the binary cannot run', () => {
+    expect(hint('/nonexistent/difyctl')).toMatchObject({ code: 0, stdout: '' })
+  })
+})

cli/scripts/install-r2.sh

@@ -22,7 +22,9 @@ trap 'rm -f "$tmp_m" "${tmp_c:-}" "${tmp_b:-}"' EXIT INT TERM
 err() { printf '%s\n' "install-r2: $*" >&2; }
 die() { err "$*"; exit 1; }
 need() { command -v "$1" >/dev/null 2>&1 || die "$1 is required"; }
+# print_skill_hint BIN: the hint names a v2 command, so a binary without it (any v1 build) gets none.
 print_skill_hint() {
+  "$1" install skills --help >/dev/null 2>&1 || return 0
   printf '%s\n' 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'
 }
 
@@ -114,7 +116,7 @@ fetch_verify_install() {
 
   printf 'difyctl %s (channel %s) installed: %s\n' "$3" "$4" "${install_dir}/difyctl"
   case ":${PATH}:" in
-    *":${install_dir}:"*) print_skill_hint ;;
+    *":${install_dir}:"*) print_skill_hint "${install_dir}/difyctl" ;;
     *) printf 'note: add %s to your PATH\n' "$install_dir" ;;
   esac
 }

cli/scripts/install-r2.test.ts

@@ -192,3 +192,31 @@ describe.skipIf(process.platform === 'win32')('install-r2.sh install_binary', ()
     expect(r.stdout.split('\n')).toEqual(['-rwxr-xr-x', 'new', 'difyctl'])
   })
 })
+
+// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".
+describe.skipIf(process.platform === 'win32')('install-r2.sh print_skill_hint', () => {
+  const fakeBins = [
+    'd="$(mktemp -d)"',
+    'printf \'#!/bin/sh\\n[ "$*" = "install skills --help" ]\\n\' > "$d/v2"',
+    'printf \'#!/bin/sh\\necho "unknown command: $*" >&2\\nexit 1\\n\' > "$d/v1"',
+    'chmod 0755 "$d/v2" "$d/v1"',
+  ]
+
+  it('prints the hint for a binary that has install skills', () => {
+    const r = lib([...fakeBins, 'print_skill_hint "$d/v2"', 'rm -rf "$d"'].join('\n'))
+    expect(r.code).toBe(0)
+    expect(r.stdout).toMatch(/difyctl install skills <skills root>/)
+  })
+
+  it('prints nothing for a binary without install skills', () => {
+    const r = lib([...fakeBins, 'print_skill_hint "$d/v1"', 'rm -rf "$d"'].join('\n'))
+    expect(r.code).toBe(0)
+    expect(r.stdout).toBe('')
+  })
+
+  it('prints nothing when the binary cannot run', () => {
+    const r = lib('print_skill_hint /nonexistent/difyctl')
+    expect(r.code).toBe(0)
+    expect(r.stdout).toBe('')
+  })
+})

cli/scripts/install.ps1

@@ -127,7 +127,11 @@ function Get-PathHint([string]$Dir) {
     return "  [Environment]::SetEnvironmentVariable('PATH', `"$Dir;`" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')"
 }
 
-function Write-SkillHint {
+# The hint names a v2 command, so a binary without it (any v1 build) gets none. Under
+# Windows PowerShell 5.1 a redirected stderr line throws when errors stop, hence the catch.
+function Write-SkillHint([string]$Bin) {
+    try { & $Bin install skills --help *> $null } catch { return }
+    if ($LASTEXITCODE -ne 0) { return }
     Write-Host 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'
 }
 
@@ -182,7 +186,7 @@ function Invoke-Main {
         }
         else {
             Write-Host 'verify: run "difyctl version"'
-            Write-SkillHint
+            Write-SkillHint $targetBin
         }
     }
     finally {

cli/scripts/install.ps1.test.ts

@@ -1,4 +1,6 @@
 import { spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vite-plus/test'
@@ -328,3 +330,30 @@ describe.skipIf(!PWSH)('install.ps1 install location and PATH hint', () => {
     expect(hint).not.toContain('$env:PATH')
   })
 })
+
+// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".
+// The fakes are shell scripts, so this runs where pwsh runs outside Windows.
+describe.skipIf(!PWSH || process.platform === 'win32')('install.ps1 Write-SkillHint', () => {
+  const hint = (bin: string) => runPwsh(`Write-SkillHint '${bin}'`)
+
+  it('prints the hint for a binary that has install skills, and stays quiet otherwise', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'difyctl-hint-'))
+    try {
+      const v2 = join(dir, 'v2')
+      const v1 = join(dir, 'v1')
+      writeFileSync(v2, '#!/bin/sh\n[ "$*" = "install skills --help" ]\n', { mode: 0o755 })
+      writeFileSync(v1, '#!/bin/sh\necho "unknown command: $*" >&2\nexit 1\n', { mode: 0o755 })
+      expect(hint(v2)).toMatchObject({
+        code: 0,
+        stdout: expect.stringContaining('difyctl install skills <skills root>'),
+      })
+      expect(hint(v1)).toMatchObject({ code: 0, stdout: '' })
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('prints nothing when the binary cannot run', () => {
+    expect(hint('/nonexistent/difyctl')).toMatchObject({ code: 0, stdout: '' })
+  })
+})