Dify CLI Docs

Dify CLI Documentation

Not an entry point: dify-docs-write loads this pack for en/cli/ pages and the Enterprise develop/cli/ trees.

Readers

Developers, DevOps engineers, and technical PMs who have a Dify account and sign in through the browser device flow. They know their shell and tools like kubectl and gh, so never explain shell basics. They may not know Dify's concepts: one sentence and a link to the main docs, never a re-teach. The "Integrate Your Agents" section is for engineers wiring their own agent to call Dify apps as tools; write for that builder, at engineering depth, and keep it distinct from building agents inside Dify Studio. SSO sign-in (dfoe_ tokens) is Enterprise-only and is documented only in the Enterprise trees.

Source of truth (S2)

Every behavior claim is verified in cli/ on langgenius/dify origin/main, read at the pinned SHA per writing-guides/index.md § "Syncing the Dify codebase safely", and the report records that SHA. Not feat/cli, not cli/README.md, not the CLI's own help text: all three drift from what shipped. Where to look:

• exact strings and exit codes: the e2e suite cli/test/e2e/suites/**
• flags and args: cli/src/commands/<verb>/<resource>/index.ts (verb-only commands in cli/src/commands/<verb>/index.ts)
• error codes: cli/src/errors/codes.ts
• env vars: cli/src/env/registry.ts

A claim you cannot verify is left out or marked {/* VERIFY: … */}, never softened into a fact. For project context (known bugs, what is shipped versus planned), ask the user.

Three rules that protect users

• The only documented way to authenticate is the browser device flow. DIFY_TOKEN and other non-interactive tokens are never shown as working auth, because readers copy auth examples into scripts.
• Runnable examples never contain <your-app-id>: app and workspace IDs are UUID-shaped, because a non-UUID fails validation and the reader's first attempt errors. The reader's own identity is <your-*>; values they received stay concrete.
• The en/cli/ doc set launched CE-first. Cloud-only content, which is anything that needs more than one workspace (workspace switching and membership, --workspace, -A), carries <Badge color="blue">Cloud</Badge> on its heading or list item rather than a "Cloud only" sentence; CE prose has one workspace and no "another workspace" framing.
• Host examples use dify.example.com, never cloud.dify.ai, and since auth login defaults to cloud.dify.ai, steer the reader to enter their host rather than stating the default. If a CE release requires removing Cloud-only sections, list the exact sections and stop for approval, then remove them in a dedicated commit so git history can restore them. The Enterprise trees have multiple workspaces, so these edition rules do not apply there.

House style

A command section opens with when and why you would run it, front-loads its key limitation, and shows real terminal output, because a reader scanning for their case decides in the first line whether to stay. The vocabulary and conventions this doc set has settled on:

• host vs server. "host" is the connection target (--host, hosts.yml, use host, "Active host", "known hosts"); "server" is the backend acting ("the server returns", "Network or server error") or its version ("client and server versions").
• JSON, described plainly. "A data array with the paging fields page/limit/total/has_more"; error JSON is "a structured JSON object". Never "envelope".
• App types as the product names them: Chatbot, Chatflow, Agent, Workflow, Text Generator. API mode names (chat, advanced-chat, …) only inside literal output.
• Configurable values. When a value can be set by flag, env var, and config, say which wins in a way that leaves no doubt; a numbered list often reads clearest for a chain. A chained "A overrides B, which overrides C" leaves the referent of "which" unclear, and a bare "or" hides the order. "Override" is fine with one clear referent ("the --limit flag overrides DIFY_LIMIT") or a named, linked target.
• Openers stay general over volatile lists; the table carries the specifics, so a new config key changes one row rather than the opener.
• Cross-references make the command the actor ("Run auth devices list to see your sessions"), and an owned fact is linked with a short payoff instead of re-explained.
• Backtick the typeable token, not the category word ("list commands such as get app").
• No version numbers in prose (the version page shows real output), no "See Also" sections, and shipped reality only, except a fix the user confirms is in flight, verified before publish.