Help

The difyctl help system covers four surfaces: the top-level overview, per-command and group help, guide topics, and a machine-readable form of all of them. All help prints to stdout and exits 0.

Get Help#

Four invocations show the same top-level overview:

difyctldifyctl helpdifyctl --helpdifyctl -h

The overview lists every command with its one-liner, three getting-started examples, the global flags, and the guide topics. For the same inventory with links into this reference, see the Command Index.

Help for One Command or Group#

Append --help to any command, or put help in front of it:

difyctl run app --helpdifyctl help run app

Per-command help shows the command’s description, usage line, arguments, flags with defaults, and examples.

Name a command group instead of a command to list the group’s subcommands:

difyctl auth --help

COMMANDS  auth devices list    List active sessions for the current bearer  auth devices revoke  Revoke one or all session devices  auth list            List all authenticated contexts (host + account pairs)  auth login           Sign in to Dify via OAuth device flow  auth logout          Log out of the active Dify host  auth whoami          Print the active subject's identity

A name that matches neither a command, a topic, nor a group fails with unknown help topic: <name>, suggestions, and exit code 1.

Guide Topics#

Long-form topics ship inside the CLI, read with difyctl help <topic>:

These topics are built into the CLI. For which variables difyctl actually reads, see Environment Variables.

Machine-Readable Help#

Every help surface accepts -o json and -o yaml. A coding agent driving difyctl works from two of them: the compact command map to pick a command, then that command’s descriptor for its arguments and flags. The full document adds the cross-command contract and the topic list in one read.

Compact Command Map#

Add --compact to top-level help to get every command as a three-field entry:

• Its command path
• One-line description
• effect label (read, write, or destructive)

Nothing else is included, so the whole map stays small enough to read in one pass before choosing a command:

difyctl help -o json --compact

The first entries of the map:

{  "commands": [    {      "command": "auth devices list",      "description": "List active sessions for the current bearer",      "effect": "read"    },    {      "command": "auth devices revoke",      "description": "Revoke one or all session devices",      "effect": "destructive"    },    {      "command": "auth list",      "description": "List all authenticated contexts (host + account pairs)",      "effect": "read"    },    {      "command": "auth login",      "description": "Sign in to Dify via OAuth device flow",      "effect": "write"    }  ]}

--compact applies to top-level help only and needs -o json or -o yaml. On per-command help, or without a structured format, it fails as a usage error with exit code 2.

Per-Command Descriptor#

Once a command is chosen, its descriptor supplies everything the map leaves out. Both per-command help forms return it:

difyctl help auth whoami -o jsondifyctl auth whoami --help -o json

{  "command": "auth whoami",  "description": "Print the active subject's identity",  "effect": "read",  "args": [],  "flags": [    {      "name": "json",      "char": null,      "type": "boolean",      "default": false,      "multiple": false,      "options": null,      "description": "emit JSON"    }  ],  "examples": [    "difyctl auth whoami",    "difyctl auth whoami --json"  ],  "agentGuide": null}

Each descriptor carries the command’s arguments and flags with types and defaults, its examples, the effect label, and an agentGuide string of command-specific guidance for agents, where one exists.

Full Document#

Without --compact, top-level help emits the complete command surface in one document:

difyctl help -o json

The document has four top-level keys:

• bin: the executable name, difyctl
• contract: exit codes, output formats, the shape of error output, and cross-command rules
• commands: one full descriptor per command
• topics: the guide topics by name and one-line summary; each topic’s text comes from difyctl help <topic>

Exit Codes#

See Output Formats and Exit Codes for the full scheme.