Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
feat(cli): add a compact command map for agent discovery (#41226)
samzong1299d99b2d70
diff --git a/cli/README.md b/cli/README.mdindex bde55e4bfe9..b9de444b980 100644--- a/cli/README.md+++ b/cli/README.md@@ -48,11 +48,13 @@ Background docs: `difyctl help account`, `difyctl help external`, `difyctl helpRun `difyctl --help` for the full list of commands.Run `difyctl <cmd> --help` for per-command reference.-For agents (and scripting), start with `difyctl help agent` — the cross-command operating guide (output, discovery, auth, exit codes, errors, HITL, retry). Every help surface is also machine-readable: `difyctl help -o json` dumps the whole command tree plus the global contract (exit codes, output formats, error envelope, HITL protocol), and `difyctl <cmd> --help -o json` returns one command's descriptor.+Use `difyctl help -o json --compact` to read the complete command map, then inspect the selected command with `difyctl help <path> -o json` before running it — that per-command descriptor is the only surface that carries args and flags.++For agents (and scripting), start with `difyctl help agent` — the cross-command operating guide (output, discovery, auth, exit codes, errors, HITL, retry). Every help surface is also machine-readable: `difyctl help -o json` dumps the whole command tree plus the global contract (exit codes, output formats, error envelope, HITL protocol), and `difyctl help <path> -o json` returns one command's descriptor.## Agent skill-`difyctl skills install` installs a single, pure-delegation `SKILL.md` into your local agents so they auto-load it. The skill does not freeze the command set — it points the agent at `difyctl help -o json` for the live surface, so it never drifts from your binary. It is embedded in the binary (version-stamped) rather than checked in.+`difyctl skills install` installs a single, pure-delegation `SKILL.md` into your local agents so they auto-load it. The skill does not freeze the command set — it directs the agent through the live compact sitemap and per-command help, so it never drifts from your binary. It is embedded in the binary (version-stamped) rather than checked in.- `difyctl skills install` — dry-run: detect installed agents (Claude Code, Codex, opencode, Cursor, pi) and print where the skill would land. Writes nothing.- `difyctl skills install --yes` — write to every detected agent, printing each path. `--agent claude-code[,cursor]` restricts to a subset; `<dir>` forces one explicit directory (handy when your agent isn't detected).diff --git a/cli/src/framework/help.test.ts b/cli/src/framework/help.test.tsindex a85510173d5..3fef2a830f1 100644--- a/cli/src/framework/help.test.ts+++ b/cli/src/framework/help.test.ts@@ -205,4 +205,31 @@ describe('formatTopLevelHelp', () => {expect(obj.commands.every((c: { effect?: string }) => typeof c.effect === 'string')).toBe(true)expect(obj.topics.map((t: { name: string }) => t.name)).toContain('account')})++ it('emits only command, description, and effect when compact', () => {+ const tree: CommandTree = {+ get: {+ subcommands: {+ app: {+ command: makeCmd({+ description: 'apps',+ effect: 'read',+ flags: { output: Flags.string({ description: 'format' }) },+ }),+ subcommands: {},+ },+ },+ },+ }+ const obj = JSON.parse(formatTopLevelHelp(tree, 'json', { compact: true })) as {+ commands: Array<Record<string, unknown>>+ bin?: unknown+ contract?: unknown+ }+ expect(obj).toEqual({+ commands: [{ command: 'get app', description: 'apps', effect: 'read' }],+ })+ expect(obj.bin).toBeUndefined()+ expect(obj.contract).toBeUndefined()+ })})diff --git a/cli/src/framework/help.ts b/cli/src/framework/help.tsindex 2098f8c828c..e8fea63c522 100644--- a/cli/src/framework/help.ts+++ b/cli/src/framework/help.ts@@ -35,7 +35,7 @@ export type CommandDescriptor = {agentGuide: string | null}-function isStructured(format: string): boolean {+export function isStructured(format: string): boolean {return format === 'json' || format === 'yaml'}@@ -71,13 +71,22 @@ function agentGuideOf(ctor: CommandConstructor): string {return new C().agentGuide()}-export function describeCommand(ctor: CommandConstructor, path: string): CommandDescriptor {- const guide = agentGuideOf(ctor)-+function summarizeCommand(+ ctor: CommandConstructor,+ path: string,+): Pick<CommandDescriptor, 'command' | 'description' | 'effect'> {return {command: path,description: ctor.description ?? null,effect: ctor.effect ?? 'read',+ }+}++export function describeCommand(ctor: CommandConstructor, path: string): CommandDescriptor {+ const guide = agentGuideOf(ctor)++ return {+ ...summarizeCommand(ctor, path),args: Object.entries(ctor.args ?? {}).map(([name, def]) => ({name,required: def.required ?? false,@@ -230,13 +239,28 @@ function formatTopLevelHelpText(tree: CommandTree): string {`GUIDES\n${renderTopicRows()}`,`LEARN MORE\n` +` Use \`${BIN} <command> --help\` for details on a command.\n` +- ` New here? Run \`${BIN} help account\`. Agents: \`${BIN} help agent\` or \`${BIN} --help -o json\`.`,+ ` New here? Run \`${BIN} help account\`. Agents: \`${BIN} help agent\` or \`${BIN} help -o json --compact\`.`,]return `${sections.join('\n\n')}\n`}-export function formatTopLevelHelp(tree: CommandTree, format: string): string {+export function formatTopLevelHelp(+ tree: CommandTree,+ format: string,+ options: { compact?: boolean } = {},+): string {+ if (options.compact && isStructured(format)) {+ return serialize(+ {+ commands: collectCommands(tree).map(({ command, path }) =>+ summarizeCommand(command, path.join(' ')),+ ),+ },+ format,+ )+ }+if (isStructured(format)) {return serialize({diff --git a/cli/src/framework/run.test.ts b/cli/src/framework/run.test.tsindex 31f0a013117..9ce0df7f45e 100644--- a/cli/src/framework/run.test.ts+++ b/cli/src/framework/run.test.ts@@ -486,6 +486,39 @@ describe('run() help routing', () => {expect(result.exit).toBeUndefined()})+ it('routes `--compact` to the site map instead of the full tree', async () => {+ const result = await captureRun(tree, ['help', '-o', 'json', '--compact'])+ const obj = JSON.parse(result.stdout) as { bin?: unknown; contract?: unknown }+ expect(result.exit).toBeUndefined()+ expect(obj.bin).toBeUndefined()+ expect(obj.contract).toBeUndefined()+ })++ it('accepts every boolean spelling of `--compact`', async () => {+ const canonical = await captureRun(tree, ['help', '-o', 'json', '--compact'])+ for (const flag of ['--compact=true', '--compact=1']) {+ const result = await captureRun(tree, ['help', '-o', 'json', flag])+ expect(result.stdout, flag).toBe(canonical.stdout)+ }+ })++ it('rejects `--compact` without a structured format', async () => {+ const result = await captureRun(tree, ['help', '--compact'])+ expect(result.exit).toBe(ExitCode.Usage)+ expect(result.stderr).toContain('--compact requires -o json or -o yaml')+ })++ it('rejects `--compact` on per-command help', async () => {+ const result = await captureRun(tree, ['help', 'get', 'app', '-o', 'json', '--compact'])+ expect(result.exit).toBe(ExitCode.Usage)+ expect(JSON.parse(result.stderr)).toEqual({+ error: {+ code: 'usage_invalid_flag',+ message: '--compact is only valid on top-level help',+ },+ })+ })+it('emits a JSON descriptor for `help <cmd> -o json`', async () => {const result = await captureRun(tree, ['help', 'get', 'app', '-o', 'json'])const obj = JSON.parse(result.stdout)diff --git a/cli/src/framework/run.ts b/cli/src/framework/run.tsindex 1d1affe08a9..5c567940c12 100644--- a/cli/src/framework/run.ts+++ b/cli/src/framework/run.ts@@ -1,14 +1,29 @@import type { CommandTree } from './registry'-import { BaseError, unknownError } from '@/errors/base'+import { BaseError, newError, unknownError } from '@/errors/base'+import { ErrorCode } from '@/errors/codes'import { formatErrorForCli } from '@/errors/format'import { findTopic } from '@/help/topics'-import { formatCommandList, formatHelp, formatTopic, formatTopLevelHelp } from './help'+import { hasBooleanFlag } from './flags'+import {+ formatCommandList,+ formatHelp,+ formatTopic,+ formatTopLevelHelp,+ isStructured,+} from './help'import { stringifyOutput } from './output'import { collectCommands, findSuggestions, resolveCommand } from './registry'+function exitWithUsageError(message: string, format: string): void {+ const error = newError(ErrorCode.UsageInvalidFlag, message)+ process.stderr.write(`${formatErrorForCli(error, { format, isErrTTY: process.stderr.isTTY })}\n`)+ process.exit(error.exit())+}+export async function run(tree: CommandTree, argv: string[]): Promise<void> {if (argv.length === 0 || argv[0] === 'help' || argv.includes('--help') || argv.includes('-h')) {const format = sniffOutputFormat(argv)+ const compact = hasBooleanFlag(argv, 'compact')// The command/topic path is the leading positional run; stop at the first// flag so output flags like `-o json` never leak into resolution.const helpArgv: string[] = []@@ -19,12 +34,22 @@ export async function run(tree: CommandTree, argv: string[]): Promise<void> {helpArgv.push(a)}+ if (compact && helpArgv.length > 0) {+ exitWithUsageError('--compact is only valid on top-level help', format)+ return+ }++ if (compact && !isStructured(format)) {+ exitWithUsageError('--compact requires -o json or -o yaml', format)+ return+ }+if (helpArgv.length > 0) {const resolved = resolveCommand(tree, helpArgv)if (resolved) {const out = formatHelp(resolved.command, resolved.path.join(' '), format)- process.stdout.write(isStructuredFormat(format) ? out : `${out}\n`)+ process.stdout.write(isStructured(format) ? out : `${out}\n`)return}@@ -67,7 +92,7 @@ export async function run(tree: CommandTree, argv: string[]): Promise<void> {process.exit(1)}- process.stdout.write(formatTopLevelHelp(tree, format))+ process.stdout.write(formatTopLevelHelp(tree, format, { compact }))return}@@ -125,7 +150,3 @@ export function sniffOutputFormat(argv: readonly string[]): string {}return ''}--function isStructuredFormat(format: string): boolean {- return format === 'json' || format === 'yaml'-}diff --git a/cli/src/help/contract.ts b/cli/src/help/contract.tsindex 646f6386483..407beed6638 100644--- a/cli/src/help/contract.ts+++ b/cli/src/help/contract.ts@@ -49,14 +49,19 @@ export const CONTRACT: Contract = {},}-// Single source for the top-level GLOBAL FLAGS section: flags that work across-// commands. `-o` is parsed globally (see sniffOutputFormat); its accepted values-// come straight from CONTRACT.outputFormats so the two can never drift.+// Single source for the top-level GLOBAL FLAGS section: flags the framework+// parses before any command sees argv. `-o` is parsed globally (see+// sniffOutputFormat); its accepted values come straight from+// CONTRACT.outputFormats so the two can never drift.export const GLOBAL_FLAG_HELP: ReadonlyArray<{ label: string; description: string }> = [{label: '-o, --output <format>',description: `Output format: ${CONTRACT.outputFormats.join('|')}`,},+ {+ label: '--compact',+ description: 'Command map with only command/description/effect (top-level help, json|yaml)',+ },{ label: '-v, --verbose', description: 'Enable verbose logging' },{label: '--http-retry <n>',diff --git a/cli/src/help/skill-template.ts b/cli/src/help/skill-template.tsindex 581d6392e13..6315b10c9fc 100644--- a/cli/src/help/skill-template.ts+++ b/cli/src/help/skill-template.ts@@ -1,15 +1,3 @@-// The difyctl agent skill, in full — one hand-authored, pure-delegation file.-//-// It inlines NO command list, NO flag list, and ships no reference files. The-// command surface is discovered at runtime via `difyctl help -o json`, so this-// template has nothing to derive from the binary and nothing that can drift-// from it. `{{VERSION}}` is the only substitution; it is filled at emit time by-// renderSkill() in ./skill.-//-// RED LINE: keep this pure delegation. The moment a command or flag listing is-// added here, the embedded static copy can fall out of sync with the command-// surface — at which point it must instead be generated from the command model-// with a snapshot test (see SKILL-SPEC.md §10, decision D2).export const SKILL_TEMPLATE = `---name: difyctldescription: Drive the difyctl CLI to manage Dify apps, workspaces, members and runs. Use when the task involves difyctl or operating a Dify instance from the command line.@@ -20,10 +8,25 @@ description: Drive the difyctl CLI to manage Dify apps, workspaces, members anddifyctl is self-describing — do not guess commands.## Discover the command surface-Run \`difyctl help -o json\` for the version-current map: every command-(args, flags, examples, \`effect\`) plus the global \`contract\` (exit codes,-output formats, error envelope, HITL protocol). Treat that JSON as the-source of truth; this file only bootstraps you into it.+1. Read the complete compact sitemap:+ \`difyctl help -o json --compact\`+ Each entry contains only \`command\`, \`description\`, and \`effect\`.+2. Decide whether the request maps to one command, needs clarification, or is+ unsupported.+3. When one command is selected, inspect it:+ \`difyctl help <path> -o json\`+ Expand a multi-token path as separate shell arguments; never quote the+ entire returned path.+ That JSON is the source of truth for args, flags, examples, \`effect\`,+ and \`agentGuide\`. Never skip it — the sitemap carries no args or flags,+ so any flag you name without this step is a guess.++When the task depends on global exit codes, error envelopes, HITL, or retry+semantics, read \`difyctl help agent\`.++Do not read the full command tree. Report unsupported only after checking the+compact sitemap. Clarify only when more than one command could satisfy the+request.## The one non-obvious thing: HITL pauses are not failuresA run can pause for human input. It exits with **code 0** and emits a@@ -31,8 +34,8 @@ A run can pause for human input. It exits with **code 0** and emits aResume as the payload instructs (see \`difyctl resume app --help\`).## Before any write/destructive action-Check the command's \`effect\` (\`read\` / \`write\` / \`destructive\`) in-\`difyctl help -o json\` before running it.+Treat the inspected command's \`effect\` as the confirmation gate before+running it. Never execute a write/destructive command without confirmation.---difyctl skill v{{VERSION}} — if \`difyctl version\` differs, re-rundiff --git a/cli/src/help/skill.test.ts b/cli/src/help/skill.test.tsindex 8cae781427c..a6edf40cf71 100644--- a/cli/src/help/skill.test.ts+++ b/cli/src/help/skill.test.ts@@ -5,8 +5,6 @@ import { versionInfo } from '@/version/info'import { renderSkill } from './skill'import { SKILL_TEMPLATE } from './skill-template'-// Self-references the skill is allowed to name — operational pointers, not a-// command listing. Everything else must be discovered via `help -o json`.const SELF_REFERENCES = new Set(['resume app', 'skills install', 'version'])describe('renderSkill', () => {@@ -25,8 +23,14 @@ describe('renderSkill', () => {expect(renderSkill({ version: versionInfo.version })).not.toContain('{{')})- it('points at the machine-readable surface instead of inlining it', () => {- expect(renderSkill({ version: versionInfo.version })).toContain('difyctl help -o json')+ it('uses the compact sitemap before per-command help', () => {+ const skill = renderSkill({ version: versionInfo.version })+ expect(skill).toContain('difyctl help -o json --compact')+ expect(skill).toContain('difyctl help <path> -o json')+ expect(skill).toContain('difyctl help agent')+ expect(skill.indexOf('difyctl help -o json --compact')).toBeLessThan(+ skill.indexOf('difyctl help <path> -o json'),+ )})it('enumerates no command from the tree (zero drift surface)', () => {@@ -54,6 +58,8 @@ describe('renderSkill', () => {it('inlines no command-specific flags (only the --help pointer)', () => {const skill = renderSkill({ version: versionInfo.version })const longFlags = skill.match(/--[a-z][\w-]+/g) ?? []- for (const flag of longFlags) expect(flag, `unexpected flag in skill: ${flag}`).toBe('--help')+ const allowed = new Set(['--help', '--compact'])+ for (const flag of longFlags)+ expect(allowed.has(flag), `unexpected flag in skill: ${flag}`).toBe(true)})})diff --git a/cli/src/help/skill.ts b/cli/src/help/skill.tsindex be35d392dec..5f31c1d72f1 100644--- a/cli/src/help/skill.ts+++ b/cli/src/help/skill.ts@@ -4,11 +4,6 @@ export type RenderSkillOptions = {readonly version: string}-// Renders the difyctl SKILL.md by substituting only the version stamp into the-// hand-authored, pure-delegation template. There is no command-tree walk: the-// skill points agents at `difyctl help -o json` for the live command surface-// rather than enumerating it, so there is nothing to derive and nothing to-// drift. The single file is what `skills install` writes / prints.export function renderSkill(opts: RenderSkillOptions): string {return SKILL_TEMPLATE.replaceAll('{{VERSION}}', opts.version)}diff --git a/cli/src/help/topics.test.ts b/cli/src/help/topics.test.tsindex 14ad27f742a..a3dc4af54fc 100644--- a/cli/src/help/topics.test.ts+++ b/cli/src/help/topics.test.ts@@ -40,10 +40,12 @@ describe('account topic', () => {describe('agent topic', () => {it('covers output, exit codes, auth, errors and HITL', () => {const out = render('agent')- expect(out).toContain('-o json')expect(out).toContain('EXIT CODES')expect(out).toContain('DIFY_TOKEN')- expect(out).toContain('difyctl help -o json')+ expect(out).toContain('difyctl help <path> -o json')+ expect(out).toContain('difyctl help -o json --compact')+ expect(out).toMatch(/difyctl help -o json\s+full command tree/)+ expect(out).toContain('difyctl get app -o json')expect(out).toContain('HUMAN-IN-THE-LOOP')})})diff --git a/cli/src/help/topics.ts b/cli/src/help/topics.tsindex 3944e309be4..59e75d34e0e 100644--- a/cli/src/help/topics.ts+++ b/cli/src/help/topics.ts@@ -87,9 +87,11 @@ APP vs STUDIO-APPnoun supports.DISCOVERY- difyctl help -o json full command tree + this contract, machine-readable- difyctl get app -o json list apps (ids + modes)- difyctl describe app <id> one app's mode and input schema+ difyctl help -o json --compact complete command map for discovery+ difyctl help <path> -o json inspect the selected command; the only source of flags+ difyctl help -o json full command tree + contract for troubleshooting+ difyctl get app -o json list apps (ids + modes)+ difyctl describe app <id> one app's mode and input schemaAUTHInteractive: difyctl auth login (browser device flow)diff --git a/cli/test/e2e/suites/agent/agent-skill-workflow.e2e.ts b/cli/test/e2e/suites/agent/agent-skill-workflow.e2e.tsindex b9e972336c7..8e6b9a82c8f 100644--- a/cli/test/e2e/suites/agent/agent-skill-workflow.e2e.ts+++ b/cli/test/e2e/suites/agent/agent-skill-workflow.e2e.ts@@ -3,7 +3,7 @@** Scenario: an AI agent has loaded difyctl SKILL.md and drives difyctl to:* 1. Bootstrap - read SKILL.md via `skills install --stdout`- * 2. Discover - `help -o json` for full command surface + contract+ * 2. Discover - compact sitemap, then per-command help* 3. Auth check - no token → exit 4 + JSON error envelope* 4. Discover apps - `get app -o json`* 5. Describe app - `describe app <id> -o json`@@ -14,7 +14,7 @@* 10. Pipeline safety - no ANSI/spinner, stdout/stderr separation** PRD: §3 Agent-Driven, §5 Agent onboarding, Req 1.3/2.1/2.3/3.1-3.3- * Agent Skills PRD: §4/§5.2 SKILL.md → help -o json discovery pattern+ * Agent Skills PRD: §4/§5.2 SKILL.md → live command discovery** Groups 1-3, 9: no auth required (local mode compatible)* Groups 4-8, 10: require DIFY_E2E_TOKEN / staging — wrapped with optionalIt@@ -45,14 +45,18 @@ const itWithWorkflow = optionalIt(Boolean(E.token) && Boolean(E.workflowAppId))const itWithHitl = optionalIt(Boolean(E.token) && Boolean(E.hitlAppId))// ----------------------------------------------------------------------------// 1 + 2. Skill bootstrap → help -o json discovery+// 1 + 2. Skill bootstrap → compact sitemap → per-command help// ---------------------------------------------------------------------------describe('E2E / agent skill — bootstrap + discovery (no auth)', () => {- it('[P0] SKILL.md contains `difyctl help -o json` as the discovery entry point', async () => {+ it('[P0] SKILL.md directs agents through compact sitemap and per-command help', async () => {const r = await run(['skills', 'install', '--stdout'])expect(r.exitCode).toBe(0)- expect(r.stdout).toContain('difyctl help -o json')+ expect(r.stdout).toContain('difyctl help -o json --compact')+ expect(r.stdout).toContain('difyctl help <path> -o json')+ expect(r.stdout.indexOf('difyctl help -o json --compact')).toBeLessThan(+ r.stdout.indexOf('difyctl help <path> -o json'),+ )})it('[P0] SKILL.md enumerates no commands from the tree (zero drift surface)', async () => {@@ -102,6 +106,25 @@ describe('E2E / agent skill — bootstrap + discovery (no auth)', () => {)})+ it('[P0] `help -o json --compact` emits only command, description, and effect', async () => {+ const r = await run(['help', '-o', 'json', '--compact'])+ expect(r.exitCode).toBe(0)+ assertPipeFriendlyJson(r)+ const map = JSON.parse(r.stdout) as {+ commands: Array<Record<string, unknown>>+ bin?: unknown+ contract?: unknown+ }+ expect(map.bin).toBeUndefined()+ expect(map.contract).toBeUndefined()+ expect(map.commands.length).toBeGreaterThan(0)+ for (const command of map.commands) {+ expect(Object.keys(command)).toEqual(['command', 'description', 'effect'])+ expect(typeof command.command).toBe('string')+ expect(typeof command.effect).toBe('string')+ }+ })+it('[P0] every command in help -o json has args, flags, examples arrays', async () => {const { commands } = JSON.parse((await run(['help', '-o', 'json'])).stdout) as {commands: Array<{ command: string; args: unknown; flags: unknown; examples: unknown }>