dify/cli/docs/specs/apps.md

---
title: apps (get / describe / run)
---

# apps

> Implementation: see [`cli/src/`](../../src/). Build & test: see [`cli/README.md`](../../README.md).

App-resource commands. Split into two CLI surfaces matching server subject_type separation:

| Subject | CLI surface | Server surface |
|---|---|---|
| `dfoa_` (account) | `get apps`, `get app`, `run app` | `/openapi/v1/apps*` |
| `dfoe_` (external SSO, EE only) | `get permitted-external-apps`, `get permitted-external-app`, `run permitted-external-app` | `/openapi/v1/permitted-external-apps*` |

CLI dispatches client-side based on the cached `subject_type` from `hosts.yml` (written at `auth login` from `GET /openapi/v1/account`). Cross-surface invocation errors before any network call:

- `dfoa_` token + `get permitted-*` → `error: 'permitted-external-apps' commands are for external SSO sessions; use 'get apps' instead`. Exit 2.
- `dfoe_` token + `get app*` / `run app` → `error: 'apps' commands are for account sessions; use 'get permitted-external-apps' instead`. Exit 2.

Companion: `auth.md §HTTP contract`, `server/endpoints.md §OpenAPI — app (two surfaces, strict subject_type separation)`. Agent onboarding text (`help account` / `help external`) in `guide.md`.

## Command surface

### dfoa_ surface (account sessions; CE + EE)

| Command | Verb | Purpose |
|---|---|---|
| `difyctl get apps` | get | List apps in target workspace |
| `difyctl get app <id>` | get | Single-app metadata fetch (slim) |
| `difyctl describe app <id>` | describe | Rich detail: info + parameter schema + JSON Schema |
| `difyctl run app <id> [message]` | run | Invoke app; server dispatches by `apps.mode` |

### dfoe_ surface (external SSO; EE only)

| Command | Verb | Purpose |
|---|---|---|
| `difyctl get permitted-external-apps` | get | List apps the SSO subject can access (no workspace) |
| `difyctl get permitted-external-app <id>` | get | Single permitted-external-app metadata fetch |
| `difyctl describe permitted-external-app <id>` | describe | Rich detail for a permitted app |
| `difyctl run permitted-external-app <id> [message]` | run | Invoke a permitted app |

## `get apps` (dfoa_)

```
difyctl get apps [-w <ws>] [-A] [--mode <m>] [--name <s>] [--tag <t>...] [--limit N] [-o <fmt>]
```

Pagination is hidden by default — auto-paginates internally. Users specify `--limit` (total rows wanted); the client issues as many server pages as needed and stops at `--limit` or when `has_more=false`. No user-facing `--page` flag; see §Pagination below.

### Flow

1. Read active session from `hosts.yml` (bearer + subject_type + current workspace).
2. Pre-flight: `subject_type == "account"`? Else → cross-surface error (exit 2).
3. Resolve `workspace_id`: `-w/--workspace` flag → `DIFY_WORKSPACE_ID` env → `hosts.yml.workspace.id`. Unresolved → exit 2 `workspace_required`.
4. `GET /openapi/v1/apps?workspace_id=<ws>&page=N&limit=N&mode=...&name=...&tag=...`. Bearer auth, scope `apps:read`.
5. If `-A/--all-workspaces`: fan out across `available_workspaces`, max 4 concurrent. Concatenate.
6. Render per `-o`.

### `get app <id>` (dfoa_, single)

```
difyctl get app <id> [-w <ws>] [-o <fmt>]
```

1. Pre-flight: `subject_type == "account"`. Else cross-surface error.
2. Resolve `workspace_id` (required by server on this surface).
3. `GET /openapi/v1/apps/<id>/describe?fields=info&workspace_id=<ws>`. Bearer auth, scope `apps:read`. Slim variant — `parameters` + `input_schema` skipped server-side.
4. Render per `-o`.

### Flags

| Flag | Default | Notes |
|---|---|---|
| `-w, --workspace` | resolved per chain | Override current workspace. Required for `get app <id>` |
| `-A, --all-workspaces` | false | Client-side fan-out across all member workspaces. Visits each workspace with same auth, applies same scope + ACL filter |
| `--mode` | (all) | `chat` / `completion` / `workflow` / `agent-chat` / `advanced-chat` |
| `--name` | — | Substring match |
| `--tag` (repeatable) | — | Tag name (not UUID); server resolves within workspace |
| `--limit` | `defaults.limit` (50) | Total rows across auto-paged calls. Max 10000 |
| `-o, --output` | `defaults.format` (table) | `table` / `json` / `yaml` / `wide` / `name` |

## `get permitted-external-apps` (dfoe_, EE only)

```
difyctl get permitted-external-apps [--mode <m>] [--name <s>] [--limit N] [-o <fmt>]
```

No workspace concept. No `-w` flag. No `-A` (single deployment-wide query). No `--tag` (tags are tenant-scoped; dfoe_ is cross-tenant).

### Flow

1. Pre-flight: `subject_type == "external_sso"`. Else cross-surface error.
2. `GET /openapi/v1/permitted-external-apps?page=N&limit=N&mode=...&name=...`. Bearer auth, scope `apps:read:permitted-external`. Strict server validator — extra params → 422.
3. Auto-paginate until `--limit` or `has_more=false`.
4. Render per `-o`.

### `get permitted-external-app <id>` (dfoe_, single)

```
difyctl get permitted-external-app <id> [-o <fmt>]
```

1. Pre-flight: `subject_type == "external_sso"`.
2. `GET /openapi/v1/permitted-external-apps/<id>`. Slim metadata. 404 if app not in permitted set.

### Flags (dfoe_ list)

| Flag | Default | Notes |
|---|---|---|
| `--mode` | (all) | Same enum as dfoa_ surface |
| `--name` | — | Substring match |
| `--limit` | 50 | Total rows. Max 10000 |
| `-o, --output` | table | `table` / `json` / `yaml` / `name` (no `wide` — no workspace columns to show) |

### Pagination

Pagination is implementation detail, not user vocabulary. The flag is `--limit N` (total rows wanted). The client loops the server's `{page, limit, total, has_more, data}` envelope until either `--limit` rows have been collected or the server reports `has_more=false`.

Server-side: each `/openapi/v1/apps` call is capped at `MAX_PAGE_LIMIT` (200) rows per page. The CLI computes per-call `limit` as `min(remaining, MAX_PAGE_LIMIT)` and increments `page` until done.

Behavior summary:

- `--limit 10` → 1 server call, `?page=1&limit=10`. Returns ≤10 rows.
- `--limit 50` (default) → 1 server call, `?page=1&limit=50`. Returns ≤50 rows.
- `--limit 200` → 1 server call, `?page=1&limit=200`.
- `--limit 500` → up to 3 server calls (`page=1&limit=200`, `page=2&limit=200`, `page=3&limit=100`); short-circuits if any page returns `has_more=false`.
- `--limit 0` → reserved (rejected with `config_invalid_value`); use a positive integer or omit for the default.

Single-page raw fetch is not exposed. Agents that need page-by-page parsing should consume the JSON envelope from the server directly (`-o json` always returns the assembled `data: [...]` after auto-paging — no `page`/`has_more` keys leak into the CLI's stdout).

Output format implications:

- `table` / `wide` / `name`: rows stream to stdout as each server page arrives, with one final summary line on stderr (`fetched 312 of 312 rows`) when the loop ends.
- `json` / `yaml`: assembled into a single payload at end-of-loop and emitted once. The wire-level `{page, limit, total, has_more}` keys do not appear in CLI output; only the merged `data: [...]` array.

Errors mid-loop:

- 429 from server: respect `Retry-After` header, sleep, retry up to 3 times. After exhaustion → exit 1 with the rows already collected printed (`-o table`/`wide`/`name`) or a partial-payload error envelope (`-o json`/`yaml`).
- 5xx mid-loop: same treatment as 429 (exponential backoff, retry).
- 4xx mid-loop (other than 429): abort, surface error to stderr, exit per `auth.md §Error handling`.

### Output — list

Default text/table:

```
ID        MODE      NAME           DESCRIPTION
app_a1b2  chat      Customer FAQ   Answers product FAQ from KB...
app_c3d4  workflow  Daily Report   Generates daily ops summary...
```

Description column truncates to fit terminal width (terminal width minus other column widths). Trailing ellipsis. Sort: `updated_at DESC`.

| Format            | Columns / payload                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| `table` (default) | `ID MODE NAME DESCRIPTION` (description truncated)                                                |
| `wide`            | `ID MODE NAME DESCRIPTION TAGS UPDATED AUTHOR` (no truncation)                                    |
| `name`            | IDs only, one per line. Pipeable: `difyctl get app -o name \| xargs -I{} difyctl describe app {}` |
| `json`            | Full server payload, indented                                                                     |
| `yaml`            | Full server payload                                                                               |

With `-A`: prepend `WORKSPACE` column to table/wide; JSON/YAML wrap each row with `{workspace_id, ...row}`.

### Output — single

Same shape as list except `data` is a one-element array. `name` format emits the single ID.

### Error handling

| Server code              | CLI behavior                                                                                             |
| ------------------------ | -------------------------------------------------------------------------------------------------------- |
| 403 `wrong_surface` | `error: this surface accepts only account sessions; you're signed in as <subject_type>.` Exit 1. Should be caught client-side; surfacing it means subject_type cache is stale — CLI clears and prompts re-login. |
| 403 `insufficient_scope` | `error: token lacks scope for this operation (required=apps:read).` Exit 1 |
| 402 `license_required` (dfoe_ surface only) | `error: this deployment's enterprise license does not cover external SSO apps surface.` Exit 1 |
| 401                      | Per `auth.md §No token refresh` — clear creds, exit 4                                                    |
| 404 (single fetch)       | `error: app not found (app_id=<id>).` Exit 1                                                             |

## `describe app` (dfoa_) / `describe permitted-external-app` (dfoe_)

```
difyctl describe app <id> [-w <ws>] [-o <fmt>]              # dfoa_
difyctl describe permitted-external-app <id> [-o <fmt>]               # dfoe_
```

Surface-specific. Cross-surface invocation errors client-side (exit 2).

### Flow — `describe app` (dfoa_)

1. Pre-flight: `subject_type == "account"`. Else cross-surface error.
2. Resolve `workspace_id` (required by server on this surface).
3. `GET /openapi/v1/apps/<id>/describe?workspace_id=<ws>`. Bearer auth, scope `apps:read`.
4. Render per `-o`.

### Flow — `describe permitted-external-app` (dfoe_, EE only)

1. Pre-flight: `subject_type == "external_sso"`. Else cross-surface error.
2. `GET /openapi/v1/permitted-external-apps/<id>`. Bearer auth, scope `apps:read:permitted-external`.
3. Render per `-o`. EE returns the same `{info, parameters, input_schema}` shape; tenant resolved from app row.

### Default text output (kubectl-describe style)

```
ID:          app_a1b2c3
Mode:        chat
Name:        Customer FAQ
Description: Answers product FAQ from knowledge base.
Author:      alice@example.com
Tags:        [prod, customer-facing]

Inputs:
  industry  (string, required)
    Options: retail | finance | health
  context   (paragraph, optional)
    Max length: 4000

File upload:
  Image:    enabled (max 5, ≤10MB)
  Document: disabled

Conversation features:
  Opening statement:    "Hi! I can help you with product questions."
  Suggested questions:  3 items
```

### Output formats

| Format            | Payload                                          |
| ----------------- | ------------------------------------------------ |
| `table` (default) | Sectioned indented label:value text              |
| `json`            | Server `/describe` response, indented            |
| `yaml`            | Same, YAML                                       |

`wide` and `name` not applicable to describe (single resource); return `NoCompatiblePrinterError`.

**Server endpoint:** `GET /openapi/v1/apps/<id>/describe` — canonical "what is this app" surface. Returns `{info, parameters, input_schema}`; the openapi-namespace has no `/info` or `/parameters` routes (callers requiring slim subsets use `?fields=...`). `input_schema` is JSON Schema (Draft 2020-12) derived server-side from `user_input_form`, intended for agent tool-call payload generation. Single-request failure mode: no partial-state handling needed.

## `run app` (dfoa_) / `run permitted-external-app` (dfoe_)

```
difyctl run app <app-id> [message] [-w <ws>] [--input <k=v>]... [--conversation <id>] [--stream] [-o text|json|yaml]
difyctl run permitted-external-app <app-id> [message] [--input <k=v>]... [--conversation <id>] [--stream] [-o text|json|yaml]
```

Two commands, one runner under the hood. Surface routing identical to read paths — `run app` hits `/apps/<id>/run`, `run permitted-external-app` hits `/permitted-external-apps/<id>/run`. Cross-surface invocation errors client-side (exit 2).

### Flow — `run app` (dfoa_)

1. Pre-flight: `subject_type == "account"`. Else cross-surface error.
2. Resolve bearer + metadata from `hosts.yml`. Bearer absent → `not_logged_in`, exit 4.
3. Resolve `workspace_id` (`-w` → env → ctx). Sent in `AppRunRequest` body (informational).
4. `POST /openapi/v1/apps/<id>/run`. Bearer auth, scope `apps:run`.
5. Render response.

### Flow — `run permitted-external-app` (dfoe_, EE only)

1. Pre-flight: `subject_type == "external_sso"`.
2. Resolve bearer. Bearer absent → exit 4.
3. `POST /openapi/v1/permitted-external-apps/<id>/run`. Bearer auth, scope `apps:run`. No `workspace_id` in body — server resolves tenant from app row.
4. Render response.

CLI does NOT pre-fetch to dispatch by mode — server owns mode dispatch. CLI's job: build `AppRunRequest` from `<message>` + `--input` + `--conversation` + `--stream`; render `AppRunResponse` per mode shape returned. The `app_meta` cache (full describe blob) is consulted opportunistically for client-side input validation; cache miss non-fatal — server validates authoritatively and returns 422 with required-input names if anything is wrong.

### Universal `enable_api` gate

Both surfaces filter through `_apply_openapi_gate` (`api/services/openapi/visibility.py`). App where `enable_api = false` → 404 on both surfaces (no existence leak). See `server/middleware.md §Universal openapi gate`. No console escape hatch.

### Headers

| Header          | Value            |
| --------------- | ---------------- |
| `Authorization` | `Bearer <token>` |

Server resolves tenant from `apps.tenant_id`. App id is in URL path (no `X-Dify-App-Id` header here).

### Input

- Positional `<message>` — for chat / agent-chat / advanced-chat modes, the user message. Workflow mode rejects positional message; use `--input`.
- `--input <key>=<value>` (repeatable) — app inputs (variables configured in the app). For workflow runs, these are the workflow inputs.
- `--conversation <id>` — chat-mode only; resume an existing conversation. Stderr-printed conversation hint after first chat invocation: `--conversation <new-id>`.
- `--stream` — request SSE streaming. `agent-chat` always streams (the upstream agent step requires it); for other modes, blocking when omitted. Text output streams deltas as they arrive; `-o json` / `-o yaml` aggregate into the blocking-shape envelope at end-of-stream.

### Output

Format selected by `-o|--output`. Default `text` (human-readable).

| Format           | Behavior                                                                                                                                                                                       |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text` (default) | Per-mode rendering — chat / agent-chat / advanced-chat: assistant reply to stdout, conversation hint to stderr; completion: assistant reply to stdout; workflow: `data.outputs` JSON to stdout |
| `json`           | Raw server response to stdout, indented JSON                                                                                                                                                   |
| `yaml`           | Raw server response to stdout, YAML                                                                                                                                                            |

`wide` and `name` reserved for collection commands; return `NoCompatiblePrinterError` on `run app`.

**Not supported:** `--jq`, mermaid output, table output for run results, live progress display, usage metrics breakdown.

### Error handling

| Server code                | CLI behavior                                                                      |
| -------------------------- | --------------------------------------------------------------------------------- |
| 403 `wrong_surface`        | Subject_type mismatch (should be caught client-side). Clear subject_type cache, prompt re-login. Exit 1 |
| 403 app ACL deny           | `error: you do not have access to this app (app_id=<id>).` Exit 1                 |
| 403 `insufficient_scope`   | `error: token lacks scope for this operation (required=apps:run).` Exit 1         |
| 402 `license_required` (dfoe_ surface only) | `error: this deployment's enterprise license does not cover external SSO apps surface.` Exit 1 |
| 404 app not found          | `error: app not found (app_id=<id>).` Exit 1                                      |
| 422 validation             | Print server's validation message; surface required-input names as hints. Exit 1  |
| 401                        | Per `auth.md §No token refresh` — clear creds, exit 4                             |

## App-info cache

Single 1h-TTL store holds the full `{info, parameters, input_schema}` blob keyed by `(host, app_id)`. Slim `?fields=info` calls populate / read the same key — partial blob is upgraded on the next full fetch. Shared by `get app <id>`, `describe app`, and `run app` (no per-command duplicate caches).

Default sort: `updated_at DESC`. Tag-name match (`--tag prod`) hits every tag with that name; `-o json` disambiguates via tag IDs. `get apps -A` caps parallel workspace fan-out at 4 concurrent calls to stay under per-token rate limits. CLI renderer keys on `parameters.user_input_form` (not `input_schema`).