Find Your Apps
Rundifyctl get console_app to list your apps. Only apps with Service API access turned on are listed, and only those can be run.
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
Rundifyctl 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 todifyctl 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 therun 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’sconversation_id back with --conversation-id.
Send the app’s required variables again on every turn. A message without them fails.
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 todifyctl 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.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 fromdifyctl only in these cases:
- Old Human Input node: when the node delivers the form through Webapp.
- New Human Input node Self-Hosted: in a Workflow app, when the node’s Recipients include Initiator. Answer as the account that started the run, signed in or with a personal access token.
status is suspended. When you can answer the form, the result has one hint per action button. When the form went only to other recipients, hints is [], and the run resumes once one of them answers.
To answer, run the hint for your action, replacing each null in its inputs with your answer. To see the form’s fields first, take form_token from any hint and run difyctl describe run form, then answer with submit run form.
With the new node, check your inputs against describe run form before you submit:
- Fill in every field, leaving no
null. - Give a Paragraph field a string and a Select field one of its options.
- Use only the form’s fields as keys.
inputs break any of these, submit run form fails with invalid_input.
Whoever answers, 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.
With the new node, the form may also reach you by email or IM (instant messaging app). The first answer from any copy is the one that counts; a later
submit run form fails.Find Why a Run Failed
For a Workflow or Chatflow run, start from the failed result’srun_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.