From 1acf6e7eb68ae1943e9484562b26bda21a3a850c Mon Sep 17 00:00:00 2001
From: Xiyuan Chen <52963600+GareArc@users.noreply.github.com>
Date: Sun, 21 Jun 2026 22:56:31 -0700
Subject: [PATCH] fix(cli): document HITL pause exit code as 0, not 2 (#37737)

---
 cli/src/commands/resume/app/guide.ts | 7 ++++---
 cli/src/commands/run/app/guide.ts    | 2 +-
 cli/src/help/contract.ts             | 6 +++---
 cli/src/help/skill-template.ts       | 2 +-
 4 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/cli/src/commands/resume/app/guide.ts b/cli/src/commands/resume/app/guide.ts
index 03b904f3d5b..1483d40b9d4 100644
--- a/cli/src/commands/resume/app/guide.ts
+++ b/cli/src/commands/resume/app/guide.ts
@@ -1,14 +1,15 @@
 export const agentGuide = `
 WHEN TO USE
   Continue a workflow that paused for human input. run app (or a prior
-  resume app) exits 2 and prints a JSON object with status "paused",
+  resume app) exits 0 and prints a JSON object with status "paused",
   form_token, workflow_run_id and resolved_default_values. Resume with:
     difyctl resume app <app_id> <form_token> --workflow-run-id <id> \\
       --inputs '{"name":"Alice"}' -o json
 
 LOOP
-  A resume can pause again (exit 2 with a new form_token). Repeat until
-  exit 0. Pass --stream to print events live.
+  A resume can pause again (exit 0 with a new form_token and status
+  "paused"). Repeat until the output is no longer a pause. Pass --stream
+  to print events live.
 
 ERROR RECOVERY
   not logged in (exit 4)    difyctl auth login
diff --git a/cli/src/commands/run/app/guide.ts b/cli/src/commands/run/app/guide.ts
index 70433fb4632..2c58e01edd9 100644
--- a/cli/src/commands/run/app/guide.ts
+++ b/cli/src/commands/run/app/guide.ts
@@ -16,7 +16,7 @@ APP MODES
                          JSON object via --inputs.
   agent-chat             Conversational with autonomous tool use.
 
-HITL PAUSE (exit code 2)
+HITL PAUSE (exit code 0 — success-with-pending)
   When a workflow pauses for human input, stdout receives a JSON object
   with status "paused", form_token, workflow_run_id, and resolved_default_values.
   Resume with:
diff --git a/cli/src/help/contract.ts b/cli/src/help/contract.ts
index d4be7209280..d3a7549ecc9 100644
--- a/cli/src/help/contract.ts
+++ b/cli/src/help/contract.ts
@@ -14,9 +14,9 @@ export type Contract = {
 }
 
 const EXIT_CODE_DESCRIPTIONS: Readonly<Record<number, string>> = {
-  [ExitCode.Success]: 'success',
+  [ExitCode.Success]: 'success (also a workflow paused for human input — check stdout for status "paused")',
   [ExitCode.Generic]: 'generic error',
-  [ExitCode.Usage]: 'usage error (bad flag / missing arg), or a workflow paused for human input',
+  [ExitCode.Usage]: 'usage error (bad flag / missing arg)',
   [ExitCode.Auth]: 'auth error (not logged in / token expired)',
   [ExitCode.VersionCompat]: 'version / compatibility error',
 }
@@ -42,7 +42,7 @@ export const CONTRACT: Contract = {
   },
   hitl: {
     description:
-      'When a workflow pauses for human input, `run app` exits 2 and writes a JSON object to stdout with status "paused", form_token, workflow_run_id and resolved_default_values.',
+      'When a workflow pauses for human input, `run app` exits 0 (success-with-pending) and writes a JSON object to stdout with status "paused", form_token, workflow_run_id and resolved_default_values.',
     resume:
       'difyctl resume app <app_id> <form_token> --workflow-run-id <id> [--inputs \'{"key":"value"}\']',
   },
diff --git a/cli/src/help/skill-template.ts b/cli/src/help/skill-template.ts
index 1038a8f99ef..581d6392e13 100644
--- a/cli/src/help/skill-template.ts
+++ b/cli/src/help/skill-template.ts
@@ -26,7 +26,7 @@ output formats, error envelope, HITL protocol). Treat that JSON as the
 source of truth; this file only bootstraps you into it.
 
 ## The one non-obvious thing: HITL pauses are not failures
-A run can pause for human input. It exits with **code 2** and emits a
+A run can pause for human input. It exits with **code 0** and emits a
 \`paused\` JSON payload — this is success-with-pending, NOT a crash.
 Resume as the payload instructs (see \`difyctl resume app --help\`).