Skip to main content
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:
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.
A Chatflow run that was stopped, or that paused at a form, returns a result without conversation_id. A stopped run’s conversation still takes new messages. To have the ID in those cases, start the run with --stream: every event carries conversation_id at its top level.

​
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 stop a Workflow or Chatflow run that’s still going or paused at a Human Input form, pass its run ID to difyctl stop run. The run ID is the run_id in a suspended or incomplete result. With --stream, take workflow_run_id from the workflow_started event. For a Chatbot, legacy Agent, or Text Generator reply, use stop task instead.
Pressing Ctrl+C during a Workflow or Chatflow run stops only difyctl, not the run on the server. To stop the run too, pass its run ID to stop run.
A model call or HTTP request already under way when you stop the run still completes. In a script, a stop looks like a failure. To tell the two apart, see Check How a Run Ended.

​
Stop a Chatbot, Legacy Agent, or Text Generator Reply

To be able to stop a reply, start it with --stream. Then pass the task_id from its first event to difyctl stop task.
stop task prints {"result": "success"} even for a task ID that doesn’t exist, or a reply that has already finished. So check that the task_id is from the reply you want to stop, and run stop task while its stream is still open.A stopped reply looks finished: its stream ends with message_end, and the command that started it exits with code 0. The answer holds only what arrived before the stop. If your script uses the answer, have it record that it called stop task.

​
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, passing the paused result’s run_id as --run-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

For errors that can come from any command, see Troubleshooting on Results, Errors, and Exit Codes.
Last modified on November 4, 2026