fix(cli): align difyctl help text with actual flags and error envelope (#37728)

cli/src/help/contract.test.ts

@@ -0,0 +1,26 @@
+import type { ErrorBody } from '@dify/contracts/api/openapi/types.gen'
+import { describe, expect, it } from 'vitest'
+import { HttpClientError, newError } from '@/errors/base'
+import { ErrorCode } from '@/errors/codes'
+import { CONTRACT } from './contract'
+
+describe('errorEnvelope contract', () => {
+  // Guard against the documented shape drifting from the real envelope: build an
+  // error with every optional field populated and assert each JSON key it emits
+  // is named in the contract string. Adding/removing an envelope field without
+  // updating the doc fails here.
+  it('documents every key the real JSON envelope can emit', () => {
+    const server: ErrorBody = { code: 'app_unavailable', message: 'gone', status: 404 }
+    const err = HttpClientError.from(newError(ErrorCode.Server4xxOther, 'boom'))
+      .withHint('do x')
+      .withRequest('GET', 'https://api.dify.ai/v1/me')
+      .withHttpStatus(404)
+      .withRawResponse('{"x":1}')
+      .withServerError(server)
+
+    const env = err.toEnvelope()
+
+    for (const key of Object.keys(env.error))
+      expect(CONTRACT.errorEnvelope.shape).toContain(`"${key}"`)
+  })
+})

cli/src/help/contract.ts

@@ -38,7 +38,7 @@ export const CONTRACT: Contract = {
     description:
       'On failure the error goes to stderr. Under -o json/yaml it is a structured envelope; otherwise a human line.',
     shape:
-      '{ "error": { "code": string, "message": string, "hint"?: string, "http_status"?: number, "request"?: string } }',
+      '{ "error": { "code": string, "message": string, "hint"?: string, "http_status"?: number, "method"?: string, "url"?: string, "raw_response"?: string, "server"?: object } }',
   },
   hitl: {
     description:

cli/src/help/topics.test.ts

@@ -50,10 +50,10 @@ describe('agent topic', () => {
 })
 
 describe('external topic', () => {
-  it('mentions external bearer prefix and login flag', () => {
+  it('mentions external bearer prefix and DIFY_TOKEN onboarding', () => {
     const out = render('external')
     expect(out).toContain('dfoe_')
-    expect(out).toContain('--external')
+    expect(out).toContain('export DIFY_TOKEN')
     expect(out).toContain('DIFY_TOKEN')
   })
 

cli/src/help/topics.ts

@@ -37,8 +37,8 @@ const EXTERNAL_HELP_TEXT = `difyctl: external-SSO bearer onboarding
   smaller dataset:
 
   1. Acquire a token through your SSO provider (out of band).
-  2. Hand it to the CLI:
-       difyctl auth login --external --token "$DIFY_TOKEN"
+  2. Hand it to the CLI via the DIFY_TOKEN environment variable:
+       export DIFY_TOKEN="<your-token>"
 
   3. List apps your subject is permitted to invoke:
        difyctl get app