> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Apps

> Run your Dify apps with difyctl, pass them inputs and files, stream or stop a long run, answer a Human Input form, and find why a run failed

> [!TIP]
>
> To hand the work over to your coding agent, [set it up with the `difyctl` skill](https://docs.dify.ai/en/cli/get-started#set-up-your-coding-agent) 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.

```bash theme={null}
difyctl get console_app

# narrow by part of the name, by mode, or both
difyctl get console_app --name report --mode workflow
```

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` |

> [!NOTE]
>
> `difyctl` doesn't list or run apps built with the new Agent. Call them through the [Service API](https://docs.dify.ai/en/api-reference/guides/agent.md) 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.

```bash theme={null}
difyctl describe console_app --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b
```

## 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.

```bash theme={null}
difyctl run console_app workflow --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --inputs '{"topic": "quarterly report"}'

# read the variables from a file
difyctl run console_app workflow --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --inputs @inputs.json
```

> [!NOTE]
>
> 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`](#check-an-apps-inputs).

## Send a Message or Generate Text

Use the `run console_app` command that matches the app's type in [Find Your Apps](#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`.

```bash theme={null}
# a Chatbot or legacy Agent app
difyctl run console_app chat --app-id 0a1b2c3d-4e5f-6789-abcd-ef0123456789 --query "What are your business hours?"

# a Chatflow app with one variable
difyctl run console_app advanced_chat --app-id 3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f --query "What changed this quarter?" --inputs '{"topic": "quarterly report"}'

# a Text Generator app
difyctl run console_app completion --app-id 5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9 --inputs '{"topic": "quarterly report"}'
```

## Continue a Conversation

Pass the result's `conversation_id` back with `--conversation-id`.

```bash theme={null}
difyctl run console_app advanced_chat --app-id 3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f --query "What changed this quarter?" --inputs '{"topic": "quarterly report"}'

# reply in the same conversation, with the same variables
difyctl run console_app advanced_chat --app-id 3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f --conversation-id 9f8e7d6c-5b4a-4321-8fed-cba987654321 --query "And the quarter before?" --inputs '{"topic": "quarterly report"}'
```

> [!NOTE]
>
> 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.

```bash theme={null}
difyctl run console_app workflow --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --inputs '{"topic": "quarterly report"}' --files '{"document": "./report.pdf", "appendices": ["./q1.pdf", "./q2.pdf"]}'

# a file on the web
difyctl run console_app workflow --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --inputs '{"document": {"transfer_method": "remote_url", "url": "https://example.com/report.pdf", "type": "document"}}'
```

## 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`.

```bash theme={null}
difyctl run console_app workflow --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --inputs '{"topic": "quarterly report"}' --stream

# print only the last event
difyctl run console_app workflow --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --inputs '{"topic": "quarterly report"}' --stream --only workflow_finished
```

## 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`](#stop-a-chatbot-legacy-agent-or-text-generator-reply) instead.

```bash theme={null}
difyctl stop run --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --run-id 4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9

# no run ID, such as for a run started from the web app: list the running runs
difyctl get run --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --triggered-from app-run --status running

# for a run paused at a form, leave out --status and look for status paused
difyctl get run --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --triggered-from app-run

# check that status is stopped; it can show running for a short while first
difyctl describe run --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --run-id 4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9
```

> [!NOTE]
>
> 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](https://docs.dify.ai/en/cli/reference/results-errors-and-exit-codes.md#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`.

```bash theme={null}
difyctl stop task --app-id 0a1b2c3d-4e5f-6789-abcd-ef0123456789 --task-id 26992456-d005-4add-a26d-8dff91d5f13d
```

> [!NOTE]
>
> `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 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**](https://docs.dify.ai/en/self-host/use-dify/nodes/human-input.md#choose-who-responds) include **Initiator**. Answer as the account that started the run, signed in or with a personal access token.

A run that pauses at a form returns a result whose `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](https://docs.dify.ai/en/cli/find-and-run-commands.md#follow-hints) 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.

If your `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.

```bash theme={null}
# show the form's fields
difyctl describe run form --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --form-token Xq7Lm2RtPz9KcV4bN8wJdE

# submit with an action; use --inputs '{}' when the form has no fields
difyctl submit run form --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --form-token Xq7Lm2RtPz9KcV4bN8wJdE --action approve --inputs '{"comment": "Looks good"}'

# follow the resumed run
difyctl get run event --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --run-id 4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9 --include-state-snapshot

# keep following if the run can pause at another form later
difyctl get run event --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --run-id 4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9 --include-state-snapshot --continue-on-pause
```

> [!NOTE]
>
> 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'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`.

```bash theme={null}
difyctl get run --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --triggered-from app-run --status failed

# the run's inputs, outputs, status, and error
difyctl describe run --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --run-id 4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9

# each node; the failed one carries the error
difyctl get run node --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --run-id 4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9
```

> [!NOTE]
>
> 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. |
| `unknown flag "--task-id"` from `stop run` or `get run event` | Pass the run ID as `--run-id` instead, such as a result's `run_id`. To stop a Chatbot, legacy Agent, or Text Generator reply by its `task_id`, use [`stop task`](#stop-a-chatbot-legacy-agent-or-text-generator-reply). |
| `run_not_found` | Check that you passed the run ID, not a `task_id`, and that `--app-id` is the app the run belongs to. |
| `run_not_stoppable` | Check the run with `describe run`. If it has already ended, there's nothing to stop. If it's still running or paused at a form, it started before your server was upgraded. If it's paused and your account started it, with `difyctl` or as a test run, run `get run event` once with its run ID and `--include-state-snapshot`, then `stop run` again. Other such runs can't be stopped from `difyctl`. |
| `app_mode_mismatch` from `stop run` or `stop task` | Stop a Workflow or Chatflow run with `stop run`, and any other app's reply with [`stop task`](#stop-a-chatbot-legacy-agent-or-text-generator-reply). |
| `form_not_found` | Check that the form token is the `form_token` from the paused result's `hints`, not one from an email or IM link, and that `--app-id` is the app the run belongs to. With the new node, only the account that started the run can answer. |
| `already_submitted` or `human_input_form_submitted` | The form already has an answer: from another recipient, from your email or IM copy of the request, or from an earlier submit. The run goes on with that first answer. Follow it with `get run event`. |
| `expired` or `human_input_form_expired` | The form waited past its timeout, or the run was stopped. Run `describe run` to see how the run ended or carried on. |

For errors that can come from any command, see [Troubleshooting](https://docs.dify.ai/en/cli/reference/results-errors-and-exit-codes.md#troubleshooting) on Results, Errors, and Exit Codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.