RiskeyL · Nov 4, 2026 · Nov 3, 2026 · Nov 3, 2026 · Nov 3, 2026 · Nov 4, 2026
@@ -26,8 +26,8 @@ The agent knowledge base API uses the same three fields and adds a `failure` obj
 |:-------|:--------|:--------------|
 | 400 | The request or the app's configuration is invalid | `invalid_param`, `bad_request`, `app_unavailable`, provider errors (below) |
 | 401 | Authentication failed or access was denied | `unauthorized` |
-| 403 | This action is not permitted, or a plan limit applies | `forbidden` |
-| 404 | The resource doesn't exist or isn't visible to this key or `user` | `not_found` |
+| 403 | This action is not permitted, or a plan limit applies | `forbidden`; when the app itself can't be used, some app endpoints return `app_not_found`, `app_abnormal_status`, `app_api_disabled`, or `workspace_archived` instead |
+| 404 | The resource doesn't exist or isn't visible to this key or `user` | `not_found`; the conversation endpoints return `conversation_not_found`, `conversation_cursor_not_found`, `conversation_variable_not_found`, or `conversation_first_message_not_found` instead |
 | 413 / 415 | A file is too large or of an unsupported type | `file_too_large`, `unsupported_file_type` |
 | 429 | Too many requests right now, or a quota is exhausted | `too_many_requests`, `rate_limit_error` |
 | 500 | Something failed on Dify's side | `internal_server_error` |

@@ -28,11 +28,13 @@ You can also add `--help` or `-h` to the command itself.
 ## Run a Command
 
 <Warning>
-`difyctl` never asks you to confirm a command, even one its help labels `destructive`, such as a `delete` command.
-
-Before you run a destructive command, check the ID it targets, for example with the matching `get` command.
+`difyctl` never asks you to confirm a command, even one you can't undo. Before you run such a command, check the ID it targets, for example with the matching `get` command.
 </Warning>
 
+`help` labels the commands you can't undo as `destructive`, such as `stop run` and the `delete` commands that act on your server.
+
+If `help` shows `stop run` as `write` instead, your server or `difyctl` is too old to label destructive commands. Until both are updated, check the target of every command that isn't `read`.
+
 ### Pass Values as Flags
 
 Pass each field you need as its flag, followed by the value. A command's help lists its flags with their types, defaults, and whether they're required. For example, part of the help for `run console_app workflow`:

@@ -189,7 +189,7 @@ For any other agent, look up its skills folder in its documentation. If your age
 
 ### Keep Control of Commands and Keys
 
-Keep your agent's own approval for shell commands turned on: `difyctl` runs each command without asking first. The skill tells your agent to check with you before it deletes anything, installs an integration, or publishes an app. Whether it does depends on the AI model your agent runs on.
+Keep your agent's own approval for shell commands turned on: `difyctl` runs each command without asking first. The skill tells your agent to check with you before it installs an integration, publishes an app, or runs a command that `help` [labels `destructive`](/en/cli/find-and-run-commands#run-a-command) or shows with no label. Whether it does depends on the AI model your agent runs on.
 
 <Tip>
   To let your agent look around without asking, allow the commands that only read from your server: `difyctl get`, `difyctl describe`, and `difyctl knowledge_fs` <Badge color="blue" size="sm">Cloud</Badge>.

@@ -44,7 +44,8 @@ In a command, `<mode>` is the app's type, such as `workflow` or `advanced_chat`.
 |:--|:--|:--|
 | `run console_app <mode>` | Run an app and get its result | Service API access on |
 | `upload console_app file` | Upload a file to pass to a later run | Service API access on |
-| `stop run` | Stop a run that's still going | Service API access on |
+| `stop run` | Stop a run that's still going or paused at a Human Input form | Service API access on, Workflow and Chatflow apps only |
+| `stop task` | Stop a reply that's still streaming | Service API access on; Chatbot, legacy Agent, and Text Generator apps only |
 | `get run event` | Follow a workflow run's events | Service API access on |
 | `describe run form` | Show the Human Input form a run paused at | Service API access on |
 | `submit run form` | Answer a Human Input form | Service API access on |
@@ -111,6 +112,19 @@ In a command, `<mode>` is the app's type, such as `workflow` or `advanced_chat`.
 | `create model credential` | Save a credential for one model, such as one served by Ollama | Admin or above |
 | `set model credential` | Replace a saved credential for one model | Admin or above |
 
+## Workspace Skills <Badge color="blue">Self-Hosted</Badge>
+
+These commands manage your workspace's skills. To install the `difyctl` skill into your coding agent instead, run `install skills`.
+
+| Command | What it does | Requires |
+|:--|:--|:--|
+| `get skill` | List your workspace's skills. Filter by keyword, by tags, or both | |
+| `describe skill` | Show a skill's details, including its latest version and its `draft_hash` | |
+| `get skill version` | List a skill's published versions | |
+| `export skill` | Download a skill as a zip file: its draft, or a published version with `--version-id` from `get skill version` | |
+| `import skill` | Create a skill from a folder, or pass `--skill-id` to replace an existing skill's draft with the folder. Draft files the folder doesn't have are removed.<br/><br/>To guard against overwriting changes made to the skill since you read it, add `--draft-hash` from `describe skill` | Editor or above |
+| `publish skill` | Publish a skill's draft as a new version | Editor or above |
+
 ## Agent Knowledge Bases <Badge color="blue">Cloud</Badge>
 
 The `knowledge_fs` commands read an agent knowledge base you can view in Dify. For how to point your coding agent at one, see [From Your Coding Agent](/en/cloud/use-dify/knowledge-base/use-knowledge-in-apps#from-your-coding-agent).

@@ -28,9 +28,13 @@ In a script, read the result's `status`. A run that finished, paused, or was cut
 
 - `ended`: the run finished.
 - `suspended`: the run paused at a Human Input form. Its `hints` carry one command per action button: to [answer the form](/en/cli/run-apps#answer-a-human-input-form), run the one for your action.
-- `incomplete`: the result was cut off before the run ended, for example when you press Ctrl+C. It holds only what arrived by then. A Workflow or Chatflow run keeps going on the server: to see how it ends, pass the result's `run_id` to `difyctl describe run`.
+- `incomplete`: the result was cut off before the run ended, for example when you press Ctrl+C. It holds only what arrived by then.
+
+  A Workflow or Chatflow run keeps going on the server: pass the result's `run_id` to `difyctl describe run` to see how it ends, or to [`stop run`](/en/cli/run-apps#stop-a-run) to stop it. If there's no `run_id`, find the run in the app's [list of running runs](/en/cli/run-apps#stop-a-run).
 - `failed` (exit code 1): the run failed or was stopped, and `error.message` says why.
 
+  For a Workflow or Chatflow, pass the result's `run_id` to `difyctl describe run` to tell the two apart: a stopped run's `status` becomes `stopped`.
+
 A failed run prints its result on stdout like any other run, and nothing goes to stderr. For example, a Workflow run without its required input:
 
 ```json
@@ -123,3 +127,12 @@ Each sign-in gets 60 requests a minute. On a self-hosted server, set [`OPENAPI_R
 | `failed to fetch the catalog: …` | `catalog_unavailable` | Check that your server is up and that you signed in to the right address. |
 | `<method> <url> timed out after <ms>ms` | `network_connection` | Raise [`http.timeout`](/en/cli/reference/configuration#settings). |
 | `Internal Server Error`, HTTP 503, on every command that uses your sign-in | `server_error` | On a self-hosted server, make sure `ENABLE_OAUTH_BEARER` is set to `true`. |
+| `skills_disabled: …`, HTTP 503, on every skill command | `server_error` | On your server, make sure [`ENABLE_SKILL`](/en/self-host/deploy/configuration/environments#console-features) is set to `true`. |
+| `skill_not_found: …` | `server_error` | Check the skill ID with `get skill`. |
+| `skill_version_not_found: …` | `server_error` | Check the version ID with `get skill version`. |
+| `skill_name_conflict: …` on `import skill` | `server_error` | Another skill already has this name.<br/><br/>If that's the skill you meant to update, pass its ID from `get skill` with `--skill-id`. Otherwise, rename yours in its `SKILL.md`. |
+| `skill_name_mismatch: …` on `import skill` | `server_error` | The `name` in your `SKILL.md` doesn't match the name of the skill you passed with `--skill-id`.<br/><br/>Change it back, or leave out `--skill-id` to import the folder as a new skill. |
+| `draft_changed: …` on `import skill` | `server_error` | The skill changed after you read its `draft_hash`, such as an edit to its draft, a publish, or a rename.<br/><br/>Run `describe skill` and save the new hash, then export the current draft and merge its changes into your folder. Import with the saved hash. Importing your folder as it is would wipe those changes. |
+| `skill_package_invalid: …` on `import skill` | `server_error` | The folder isn't a valid skill package. For the format, see [Agent Skills](https://agentskills.io/home). |
+| `skill_package_invalid: …` on `publish skill` or `export skill` | `server_error` | The draft's `SKILL.md` frontmatter is invalid. In Dify, fix the field or line the error names. |
+| `request_entity_too_large: …` on `import skill` | `server_error` | The folder has too many files or is too large for your server's [skill package limits](/en/self-host/deploy/configuration/environments#upload_skill_file_size_limit).<br/><br/>Remove files the skill doesn't need, or have your server admin raise the limit the message names. |
@@ -86,6 +86,8 @@ difyctl run console_app advanced_chat --app-id 3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5
 Send the app's required variables again on every turn. A message without them fails.
 </Note>
 
+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.
@@ -110,16 +112,43 @@ difyctl run console_app workflow --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b -
 
 ## 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`:
+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
-difyctl stop run --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --task-id 26992456-d005-4add-a26d-8dff91d5f13d
+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
 ```
 
-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.
+<Info>
+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`.
+</Info>
+
+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](/en/cli/reference/results-errors-and-exit-codes#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
+difyctl stop task --app-id 0a1b2c3d-4e5f-6789-abcd-ef0123456789 --task-id 26992456-d005-4add-a26d-8dff91d5f13d
+```
 
 <Note>
-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.
+`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`.
 </Note>
 
 ## Answer a Human Input Form
@@ -132,7 +161,7 @@ A run that pauses at the form returns a result whose `status` is `suspended`, wi
 
 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.
+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.
 
 ```bash
 # show the form's fields
@@ -142,10 +171,10 @@ difyctl describe run form --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --form-t
 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 --task-id 4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9 --include-state-snapshot
+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 --task-id 4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9 --include-state-snapshot --continue-on-pause
+difyctl get run event --app-id 7f3e9a2b-1c4d-4e8f-9a0b-2d5c8e1f4a7b --run-id 4b5c6d7e-8f90-4a1b-b2c3-d4e5f6a7b8c9 --include-state-snapshot --continue-on-pause
 ```
 
 ## Find Why a Run Failed
@@ -171,5 +200,9 @@ Keep `--triggered-from app-run`. Without it, the list shows only test runs of th
 | 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.<br/><br/>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). |
 
 For errors that can come from any command, see [Troubleshooting](/en/cli/reference/results-errors-and-exit-codes#troubleshooting) on Results, Errors, and Exit Codes.
@@ -110,18 +110,22 @@ The backend services include
 
 ### Start the Worker Service
 
-To consume asynchronous tasks from the queue, such as dataset file import and dataset document updates, follow these steps to start the Worker service
+To consume asynchronous tasks from the queue, such as dataset file import and dataset document updates, follow these steps to start the Worker service.
+
+<Info>
+If you've changed `OPS_TRACE_QUEUE`, replace `ops_trace_v2` in the `-Q` list with your queue name. See [Environment Variables](/en/self-host/deploy/configuration/environments#llmops-trace-delivery) for details.
+</Info>
 
 - for macOS or Linux
     ```
-    uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q api_token,dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,app_rbac,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_publisher,trigger_refresh_executor,retention,workflow_based_app_execution,knowledge_fs_lifecycle
+    uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q api_token,dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,human_input_delivery,human_input_contact_sync,ops_trace_v2,app_deletion,app_rbac,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_publisher,trigger_refresh_executor,retention,workflow_based_app_execution,knowledge_fs_lifecycle
     ```
 
     If you are using a Windows system to start the Worker service, please use the following command instead:
 
 - for Windows
     ```
-    uv run celery -A app.celery worker -P solo --without-gossip --without-mingle --loglevel INFO -Q api_token,dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,app_rbac,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_publisher,trigger_refresh_executor,retention,workflow_based_app_execution,knowledge_fs_lifecycle
+    uv run celery -A app.celery worker -P solo --without-gossip --without-mingle --loglevel INFO -Q api_token,dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,human_input_delivery,human_input_contact_sync,ops_trace_v2,app_deletion,app_rbac,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_publisher,trigger_refresh_executor,retention,workflow_based_app_execution,knowledge_fs_lifecycle
     ```
 
     Expected output:
@@ -142,7 +146,7 @@ To consume asynchronous tasks from the queue, such as dataset file import and da
       .> dataset          exchange=dataset(direct) key=dataset
       .> generation       exchange=generation(direct) key=generation
       .> mail             exchange=mail(direct) key=mail
-      .> ops_trace        exchange=ops_trace(direct) key=ops_trace
+      .> ops_trace_v2     exchange=ops_trace_v2(direct) key=ops_trace_v2
 
     [tasks]
     . schedule.clean_embedding_cache_task.clean_embedding_cache_task