To hand the work over to your coding agent, set it up with the difyctl skill and point it to this page.
Find Your Apps#
Run difyctl get console_app to list your apps. Only apps with Service API access turned on are listed, and only those can be run.
Use an app’s id as --app-id in other commands. Its mode is the app’s type, which decides the command that runs it:
mode | App type | Run it with |
|---|---|---|
workflow | Workflow | run console_app workflow |
advanced-chat | Chatflow | run console_app advanced_chat |
chat | Chatbot | run console_app chat |
agent-chat | Legacy Agent | run console_app chat |
completion | Text Generator | run console_app completion |
difyctl doesn’t list or run apps built with the new Agent. Call them through the Service API instead.
Check an App’s Inputs#
Run difyctl describe console_app to show an app’s variables: their names, their types, and which are required.
Run a Workflow#
Pass the app’s variables to difyctl run console_app workflow in --inputs, as JSON keyed by name. The answer is the result’s outputs, keyed by the Output node’s variables.
A misspelled required variable fails the run with an error such as topic is required in input form. A misspelled optional one is silently left out. Check the variable names with describe console_app.
Send a Message or Generate Text#
Use the run console_app command that matches the app’s type in Find Your Apps. Put the message in --query and any variables in --inputs. A Text Generator app usually takes only --inputs. The response is the result’s text.answer.
Continue a Conversation#
Pass the result’s conversation_id back with --conversation-id.
Send the app’s required variables again on every turn. A message without them fails.
Send Files#
With any run command, map each file variable to a local path in --files. A file-list variable takes a list of paths. A file on the web goes in --inputs instead. Pass each file variable in either --files or --inputs, not both.
Follow a Long Run#
To watch a run as it goes, add --stream. It prints each event as it happens, one JSON object per line. In a Workflow run, the last event, workflow_finished, carries the result in data.outputs. To print only the events you want, name each one with --only.
Stop a Run#
To be able to stop a run later, start it with --stream. To stop it, pass the task_id from its first event to difyctl stop run:
A stopped Workflow or Chatflow run’s stream ends with a workflow_finished event whose data.status is stopped. The streaming command exits with code 1. In a script, check data.status, not the exit code, to see that the run was stopped.
Pass stop run the task_id, not the workflow_run_id that every event also carries. Given the wrong one, it still prints {"result": "success"}, but the run keeps going.
Answer a Human Input Form#
You can answer a form from difyctl only when the Human Input node delivers it through Webapp.
A run that pauses at the form returns a result whose status is suspended, with one hint per action button. Run the hint for your action, replacing each null in its inputs with your answer.
Or, to see the form’s fields before you answer, take form_token from any hint and use describe run form, then answer with submit run form.
Either way, follow the resumed run with get run event. Despite the flag’s name, pass the paused result’s run_id as --task-id. Keep --include-state-snapshot, or the command can sit silent for up to 5 minutes.
Find Why a Run Failed#
For a Workflow or Chatflow run, start from the failed result’s run_id, or list failed runs with difyctl get run. Then inspect the run with describe run and its nodes with get run node.
Keep --triggered-from app-run. Without it, the list shows only test runs of the draft.
Troubleshooting#
| Message | What to do |
|---|---|
invalid run input, though the inputs are right | The app may never have been published. Publish it, then run it again. |
For errors that can come from any command, see Troubleshooting on Results, Errors, and Exit Codes.