dify/cli/docs/specs/guide.md

title

title
guide

guide

Implementation: see cli/src/. Build & test: see cli/README.md.

Agent onboarding quickstart. Three subcommands under the help topic — one per bearer token type plus help environment:

difyctl help account
difyctl help external
difyctl help environment

Root difyctl --help directs agents here:

For AI agents: run 'difyctl help account' (dfoa_ token) or
'difyctl help external' (dfoe_ token).

---

difyctl help account

For dfoa_ (OAuth account) bearers. Workspace-scoped access: discovery, workspace management, invocation.

Output (stdout, static text):

difyctl Agent Guide — Account Token (dfoa_)

Surface: /openapi/v1/apps* (workspace-scoped).

Discovery:
  difyctl get apps                     # list apps in current workspace
  difyctl get apps --mode chat         # filter by mode
  difyctl get apps --name "keyword"    # filter by name
  difyctl get apps --tag "prod"        # filter by tag
  difyctl get apps -A                  # fan out across all member workspaces
  difyctl get app <id>                 # single app slim metadata
  difyctl describe app <id>            # parameters + input schema

Workspace:
  difyctl get workspace                # list your workspaces
  difyctl auth use <workspace-id>      # switch active workspace

Invocation:
  difyctl run app <id> "message"       # chat or completion
  difyctl run app <id> --input k=v     # workflow inputs (repeatable)
  difyctl run app <id> -o json         # structured output

Cross-surface:
  'permitted-external-apps' commands are for external SSO sessions only.
  Running them on a dfoa_ session errors with exit 2.

Error handling:
  All errors emit JSON to stderr when -o json is active.
  Branch on the 'code' field. Exit codes:
    0 = success
    1 = server or network error
    2 = usage / bad input
    4 = auth error (re-run 'difyctl auth login')

---

difyctl help external

For dfoe_ (External SSO) bearers. EE-only. No workspace concept. Surface: /openapi/v1/permitted-external-apps*.

Output (stdout, static text):

difyctl Agent Guide — External SSO Token (dfoe_)

Surface: /openapi/v1/permitted-external-apps* (no workspace).
Scopes: apps:run + apps:read:permitted-external.
Visibility: apps where access_mode is 'public' or 'sso_verified'.

Discovery:
  difyctl get permitted-external-apps                 # list permitted apps
  difyctl get permitted-external-apps --mode chat     # filter by mode
  difyctl get permitted-external-apps --name "kw"     # filter by name
  difyctl get permitted-external-app <id>             # single permitted-external-app metadata
  difyctl describe permitted-external-app <id>        # parameters + input schema

Invocation:
  difyctl run permitted-external-app <id> "message"   # chat or completion
  difyctl run permitted-external-app <id> --input k=v # workflow inputs
  difyctl run permitted-external-app <id> -o json     # structured output

Cross-surface:
  'apps' and workspace commands are for account sessions only.
  Running them on a dfoe_ session errors with exit 2.

Error handling:
  All errors emit JSON to stderr when -o json is active.
  Branch on the 'code' field. Exit codes:
    0 = success
    1 = server or network error
    2 = usage / bad input
    4 = auth error (re-run 'difyctl auth login')

---

No auth gate — onboarding runs even when not logged in. Text is static, not generated from server state.