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.
AGENTS.md — src/commands/
Per-command agent-optimized usage and structure guide.
Command folder convention
Every command is a folder. index.ts is the command class file. All related
code — business logic, helpers, tests — colocates inside the folder.
Subcommands are subfolders.
src/commands/
<topic>/
<verb>/
index.ts ← command class (extends Command; the ONLY file the registry discovers)
helpers.ts ← optional behavior owner (not a command, invisible to the registry)
*.test.ts ← tests
<nested-verb>/ ← subcommand (e.g. ops/describe/)
index.ts
_shared/ ← intra-topic shared code (only when needed by 2+ siblings)
<shared>.ts
The registry generator (pnpm tree:gen → src/commands/tree.generated.ts) discovers
commands only via **/index.+(js|cjs|mjs|ts). All other files in command
folders are invisible to the registry — add freely without glob exclusions.
Folders prefixed with _ are excluded from registry discovery.
The command class extends Command<typeof INPUT> (src/plugins/commands/command.ts):
export default class MyCmd extends Command<typeof INPUT> {
static override summary = 'One-line description'
static override effect = 'write' as const // 'read' (default) | 'write' | 'destructive'
static override input = INPUT // a Zod object; also the argv parser's schema
static override positional = ['id'] as const // optional; maps positional argv to input keys
static override examples = [{ title: '...', input: { id: '...' } }] // optional
static override hidden = true // optional; keeps the command out of help, not out of the tree
async run(input: z.infer<typeof INPUT>, ctx: CommandContext) {
// read plugin services with ctx.get(...); the return value is printed as
// indented JSON. Return an Outcome for a non-zero exit or output already
// written through ctx.get(io); notices go to ctx.get(io).notice(...).
}
}
schema() is the JSON Schema help documents and finalize validates, derived from
input; flags() is what the argv parser accepts (default: schema());
facets() is the op half of the descriptor (default: none); finalize(input, path)
is the one input gate, throwing input_invalid and then applying the Zod defaults.
Only the catalog-op adapter overrides them.
run's return value is the JSON value printed to stdout; there is no separate
output-formatting step and no agentGuide — --help on any command prints the
same descriptor (summary, effect, input, positional, examples, plus
kind, bind, pins for a catalog operation) that difyctl help <id> prints.
Adding a new command
- Create
src/commands/<topic>/<verb>/index.tsextendingCommand. - Keep small owner-local behavior in
index.ts; extract a sibling module when logic needs independent tests, reuse, or a clearer owner. - Run
pnpm tree:gento regenerate the command tree (also runs implicitly viaprebuild/predev/pretest). - Run
pnpm testto verify coverage.
Shared utilities
Code used by two or more commands lives in a top-level domain folder (e.g.
src/call/, src/errors/) or on a plugin service, never inside a
command folder. One command never imports from another command's folder.
A command imports a plugin through @/plugins/<name> and reads it with
ctx.get(...). The framework files are the exception:
plugins/commands/{command,cancel,registry}.ts and plugins/argv/parse.ts.