Help - Dify Docs

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:

difyctl
difyctl help
difyctl --help
difyctl -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 --help
difyctl 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>:

Topic	What it covers
`account`	Onboarding guidance.
`environment`	The CLI’s own descriptions of the `DIFY_*` environment variables.
`agent`	The cross-command contract for agents driving `difyctl`.

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 json
difyctl 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

Code	Meaning
`0`	Help printed
`1`	Unknown help topic or command name
`2`	`--compact` outside top-level `-o json` or `-o yaml` help

See Output Formats and Exit Codes for the full scheme.

​Get Help

​Help for One Command or Group

​Guide Topics

​Machine-Readable Help

​Compact Command Map

​Per-Command Descriptor

​Full Document

​Exit Codes