Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

feat(cli): let agents build Dify apps with difyctl and an embedded skill (#43819)

Xiyuan Chen1fefc5272390
diff --git a/.github/workflows/cli-edge.yml b/.github/workflows/cli-edge.yml
index 8df4bc3bac2..14d94c517e1 100644
--- a/.github/workflows/cli-edge.yml
+++ b/.github/workflows/cli-edge.yml
@@ -57,7 +57,7 @@ jobs:
run: CLI_VERSION="${{ steps.ver.outputs.version }}" scripts/release-write-checksums.sh
- name: Smoke the runner-arch binary
- run: ./dist/bin/difyctl-v${{ steps.ver.outputs.version }}-linux-x64 version
+ run: scripts/release-smoke.sh "./dist/bin/difyctl-v${{ steps.ver.outputs.version }}-linux-x64"
- name: Publish to R2
env:
diff --git a/.github/workflows/cli-release.yml b/.github/workflows/cli-release.yml
index d87b21dbe6b..aba7dc3a471 100644
--- a/.github/workflows/cli-release.yml
+++ b/.github/workflows/cli-release.yml
@@ -121,6 +121,9 @@ jobs:
- name: Generate sha256 checksum file
run: scripts/release-write-checksums.sh
+ - name: Smoke the runner-arch binary
+ run: scripts/release-smoke.sh "./dist/bin/$(node scripts/release-naming.mjs asset "$version" linux-x64)"
+
- name: Attach difyctl assets to Dify release
if: ${{ !inputs.dry_run }}
env:
diff --git a/cli/.bun-version b/cli/.bun-version
index 17e63e7affd..9df886c42a1 100644
--- a/cli/.bun-version
+++ b/cli/.bun-version
@@ -1 +1 @@
-1.3.11
+1.4.2
diff --git a/cli/AGENTS.md b/cli/AGENTS.md
index c40e4b8309c..cb835c0c94e 100644
--- a/cli/AGENTS.md
+++ b/cli/AGENTS.md
@@ -8,6 +8,7 @@ This package is the ESM TypeScript implementation of `difyctl`. Use the Node.js
- Plugins under `src/plugins/` (`argv global-flags env config session token catalog http ops io commands`) own state. A plugin's `build()` closes over its own cache or loaded document; nothing outside a plugin reaches into another plugin's internals. Outside a plugin folder, import only `@/plugins/<name>` and use the service from `ctx.get(...)`; the command framework (`plugins/commands/command.ts`, `cancel.ts`, `registry.ts`) and the argv parser (`plugins/argv/parse.ts`) are the only modules imported directly.
- `src/protocol/` and `src/call/` are pure modules: catalog-shape logic (kinds, bind, pins, fold) and the `call` flag table, request-building and rendering, with no op-specific branching anywhere under `src/call/` — kind and bind dispatch go through the tables in `src/protocol/` and `src/call/render/`, keyed by the catalog's own `kind`/`bind` values, never by operation id.
- Preserve exit codes and the JSON output contract during refactors. Do not add dependencies or compatibility shims unless the task explicitly requires them.
+- Local YAML files go through `localFile` (`src/store/local-file.ts`), one schema each, no versions. Never change a key's name/type/meaning; add a new key (it may fall back to the old one).
- `ARD.md` owns CLI code structure. Keep behavior aligned with the real mock-server (`test/fixtures/dify-mock/`) behavior tests.
## Commands
diff --git a/cli/ARD.md b/cli/ARD.md
index 92ee95ca6df..2cf0896b460 100644
--- a/cli/ARD.md
+++ b/cli/ARD.md
@@ -25,7 +25,7 @@ src/
net/ fetch init and proxy dispatcher, shared by the http plugin and the pre-login device flow
store/ config/session/token file and keychain persistence
sys/ the process edges — env, argv, exit, platform paths; io/ holds streams.ts, color.ts and view.ts (a JSON value paired with its text form, the mode picks one)
- skills/ reads skills from a GitHub folder or a local folder, and installs them
+ skills/ the one embedded difyctl skill (or a local folder) and its installer
```
---
@@ -74,7 +74,7 @@ import { ErrorCode } from '@/errors/codes'
throw new BaseError({
code: ErrorCode.UsageMissingArg,
message: 'workspace id required',
- hint: "pass --workspace or run 'difyctl use workspace <id>'",
+ hint: "pass --workspace-id or run 'difyctl use workspace <id>'",
})
```
diff --git a/cli/README.md b/cli/README.md
index 5abe04f0c8f..1b389e8721e 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -2,6 +2,18 @@
CLI client for the [Dify] platform. Browser device-flow sign-in, then a server-published catalog of operations you discover and call at run time, each one a command. Results are JSON; help and errors are text on a terminal, JSON in a pipe.
+## Install
+
+difyctl ships as assets on Dify releases. The installer picks the build from the latest release; set `DIFY_VERSION` to match your Dify server:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-cli.sh | sh
+```
+
+Windows (PowerShell): `irm https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install.ps1 | iex`.
+
+The binary goes to `$HOME/.local/bin` (Windows: `%LOCALAPPDATA%\difyctl\bin`). Every installer accepts `DIFYCTL_INSTALL_DIR` (the bin folder itself) and `DIFYCTL_PREFIX` (the folder above it, so the binary lands in `<prefix>/bin`); `DIFYCTL_INSTALL_DIR` wins when both are set.
+
## Install (edge, internal)
Per-commit `edge` builds are published to Cloudflare R2. The installer script lives in this repo; binaries are fetched from R2 via `DIFYCTL_R2_BASE` (shared internally):
@@ -10,15 +22,16 @@ Per-commit `edge` builds are published to Cloudflare R2. The installer script li
curl -fsSL https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-r2.sh | DIFYCTL_R2_BASE=<BASE> sh
```
-| Env | Default | Purpose |
-| ----------------------- | ------------------ | ------------------------------------------------------------------- |
-| `DIFYCTL_R2_BASE` | — (required) | R2 public base, e.g. `https://pub-….r2.dev`. |
-| `DIFYCTL_CHANNEL` | `edge` | Channel to install. |
-| `DIFYCTL_INSTALL_DIR` | `$HOME/.local/bin` | Directory the binary is written to (`<dir>/difyctl`). |
-| `DIFYCTL_VERSION` | latest | Pin an exact published version. |
-| `DIFYCTL_COMMIT` | latest | Pin by git commit (short or full sha). |
-| `DIFYCTL_R2_PREFIX` | `difyctl` | R2 key root for the pointer JSONs (`manifest.json` / `index.json`). |
-| `DIFYCTL_R2_BIN_PREFIX` | `difyctl/bin` | R2 key root for binaries (the lifecycle/TTL target). |
+| Env | Default | Purpose |
+| ----------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `DIFYCTL_R2_BASE` | — (required) | R2 public base, e.g. `https://pub-….r2.dev`. |
+| `DIFYCTL_CHANNEL` | `edge` | Channel to install. |
+| `DIFYCTL_INSTALL_DIR` | `$HOME/.local/bin` | Directory the binary is written to (`<dir>/difyctl`). On Windows the default is `%LOCALAPPDATA%\difyctl\bin`. |
+| `DIFYCTL_PREFIX` | `$HOME/.local` | Used as `<prefix>/bin` when `DIFYCTL_INSTALL_DIR` is unset. On Windows the default is `%LOCALAPPDATA%\difyctl`. |
+| `DIFYCTL_VERSION` | latest | Pin an exact published version. |
+| `DIFYCTL_COMMIT` | latest | Pin by git commit (short or full sha). |
+| `DIFYCTL_R2_PREFIX` | `difyctl` | R2 key root for the pointer JSONs (`manifest.json` / `index.json`). |
+| `DIFYCTL_R2_BIN_PREFIX` | `difyctl/bin` | R2 key root for binaries (the lifecycle/TTL target). |
By default the channel pointer (latest build) is installed. Set `DIFYCTL_COMMIT` (e.g. `ce4af86`) or `DIFYCTL_VERSION` to install a specific past build — both resolve through the channel's `index.json`:
@@ -37,6 +50,7 @@ difyctl login --server https://dify.example.com # opens the browser; approve t
difyctl help # the map: every command and operation namespace
difyctl help chatbot # search commands and operations by plain words
difyctl get workspace # workspaces visible to this account
+difyctl describe workspace # the workspace difyctl uses
difyctl get console_app --limit 5 # list apps
difyctl run console_app workflow --app-id <id> --inputs @vars.json --stream
```
@@ -45,21 +59,20 @@ difyctl has no built-in business commands. Every operation the server publishes
## Commands
-| Command | Purpose |
-| -------------------------- | --------------------------------------------------------------- |
-| `login` | Log in via the OAuth device flow |
-| `logout` | Log out of the current session |
-| `version` | Print the client and (if logged in) server versions |
-| `use workspace <id>` | Pin the local session to a workspace |
-| `get config [key]` | Print the local config, or one key |
-| `set config <key> <value>` | Set a local config value |
-| `unset config <key>` | Remove a local config value, restoring its default |
-| `refresh cache` | Refetch the server catalog and replace the local cache |
-| `delete cache` | Delete the local server catalog cache |
-| `get skills` | List the skills in the collection |
-| `install skills <dir>` | Write skills from the collection into a skills root (`--skill`) |
-
-`login` blocks until the browser approval arrives. An agent runs it in the background, relays the `open <url>` and `code <code>` lines from its stderr to the user, and does not cancel the job. In a sandbox it adds `--no-keyring` and sets `DIFY_CONFIG_DIR` to persistent storage on every call, so the login survives the next session.
+| Command | Purpose |
+| -------------------------- | ------------------------------------------------------ |
+| `login` | Log in via the OAuth device flow |
+| `logout` | Log out of the current session |
+| `version` | Print the client and (if logged in) server versions |
+| `use workspace <id>` | Pin this device to a workspace you belong to |
+| `get config [key]` | Print the local config, or one key |
+| `set config <key> <value>` | Set a local config value |
+| `unset config <key>` | Remove a local config value, restoring its default |
+| `refresh cache` | Refetch the server catalog and replace the local cache |
+| `delete cache` | Delete the local server catalog cache |
+| `install skills <dir>` | Write the difyctl skill into a skills root (`--from`) |
+
+`login` needs `--server`; there is no default server. It blocks until the browser approval arrives. An agent uses `--no-wait` instead: it gives the user the URL and code, then runs `login --resume` after the user approves. If it sets `DIFY_CONFIG_DIR`, it sets it on every call.
`--verbose` is global: it may appear on any command, and it keeps the raw server
response in the error envelope instead of dropping it.
@@ -68,11 +81,9 @@ response in the error envelope instead of dropping it.
## Agent skills
-difyctl installs agent skills from [`skills/`] at the repo root. It downloads them from GitHub at install time, from the commit the binary was built from; the binary holds no copy and needs no git. The basic skill, `difyctl`, teaches the discovery flow — `help` to see the map or search, `help <id>` to inspect one operation, then the operation's own command to run it — so it stays correct as the server's catalog grows. Scenario skills add guidance for one kind of task and open by reading the basic one.
+difyctl ships one skill, `difyctl`, built into the binary. It teaches the discovery flow — `help` to see the map or search, `help <id>` to inspect one operation, then the operation's own command to run it — so it stays correct as the server's catalog grows. The skill is a tree of linked docs under [`skills/difyctl/`].
-- `difyctl get skills` — the collection: each skill's name and description. Writes nothing.
-- `difyctl install skills <dir>` — write every skill into `<dir>`, the agent's skills root: the folder that holds one subfolder per skill, for example `~/.claude/skills` for Claude Code or `~/.codex/skills` for Codex. Each skill's folder is replaced whole. `--skill <name>` (repeatable) writes only those skills; a scenario skill brings `difyctl` along.
-- `--from` on both reads skills from elsewhere: any GitHub folder in the standard layout (`https://github.com/<owner>/<repo>/tree/<ref>/<folder>`), or a local folder when GitHub is blocked. Set `GITHUB_TOKEN` if GitHub's rate limit (60 requests an hour per IP) gets in the way.
+- `difyctl install skills <dir> [--from <folder>]` — write the skill into `<dir>`, the agent's skills root: the folder that holds one subfolder per skill, for example `~/.claude/skills` for Claude Code or `~/.codex/skills` for Codex. The `difyctl` folder is replaced whole. It works offline. `--from` installs a local skill folder instead of the built-in one.
difyctl does not detect agents. You name the root, and re-running the same command refreshes the copies.
@@ -88,7 +99,7 @@ The same files install through the Vercel skills installer: `npx skills add lang
`get config [key]` prints the whole local config or one key; `set config <key> <value>` and `unset config <key>` change it. The only config key today is `http.timeout` (request timeout in milliseconds).
-Tokens use the OS keychain by default, falling back to `tokens.yml` on hosts without one; `login --no-keyring` chooses the file outright. Config and cache files are written `0600`, their directory `0700`.
+Tokens use the OS keychain by default, falling back to `tokens.yml` in the config folder on hosts without one. On Linux without a DBus session (`DBUS_SESSION_BUS_ADDRESS` unset), the keychain would only hold the token until the session ends, so difyctl uses `tokens.yml` there too; `login --no-keyring` chooses the file outright. The catalog cache is kept in the config folder under `catalog/`; `DIFY_CACHE_DIR` is no longer used. Config and cache files are written `0600`, their directory `0700`.
| Env var | Effect |
| ------------------- | ----------------------------------------------------------- |
@@ -97,7 +108,6 @@ Tokens use the OS keychain by default, falling back to `tokens.yml` on hosts wit
| `DIFY_WORKSPACE_ID` | Overrides the locally pinned workspace |
| `DIFY_OUTPUT` | `json` or `text`; overrides the terminal/pipe detection |
| `DIFY_CONFIG_DIR` | Overrides the config directory |
-| `DIFY_CACHE_DIR` | Overrides the catalog cache directory |
Resource access tokens can also be passed through `DIFY_TOKEN`. They can list
their own workspace and discover only apps bound to that token; workspace
@@ -111,7 +121,7 @@ Pass `--stream` on a streaming operation to print every event as one JSON line,
difyctl run console_app chat --app-id … --query hello --inputs '{}' --stream
```
-`--only <event>` filters the streamed events to the named event types; repeat it to keep more than one. Without `--stream`, a streaming operation's events fold into `{status, text, outputs?, message_id?, conversation_id?, error?, hints}`.
+`--only <event>` filters the streamed events to the named event types; repeat it to keep more than one. Without `--stream`, a streaming operation's events fold into `{status, text, outputs?, message_id?, conversation_id?, run_id?, error?, hints}`.
## Exit codes
@@ -135,4 +145,4 @@ Apache-2.0.
[Agent skill]: #agent-skills
[Dify]: https://dify.ai
[`ARD.md`]: ARD.md
-[`skills/`]: ../skills
+[`skills/difyctl/`]: ../skills/difyctl
diff --git a/cli/bin/dev.js b/cli/bin/dev.js
index fb6a702ba22..5045e5e89fc 100755
--- a/cli/bin/dev.js
+++ b/cli/bin/dev.js
@@ -9,6 +9,7 @@ globalThis.__DIFYCTL_VERSION__ = info.version
globalThis.__DIFYCTL_COMMIT__ = info.commit
globalThis.__DIFYCTL_BUILD_DATE__ = info.buildDate
globalThis.__DIFYCTL_CHANNEL__ = info.channel
+globalThis.__DIFYCTL_COMPILED__ = false
const { main } = await import('../src/main.ts')
process.exitCode = await main(process.argv.slice(2))
diff --git a/cli/scripts/install-cli.sh b/cli/scripts/install-cli.sh
index 7bd87886c35..5271344a9c3 100755
--- a/cli/scripts/install-cli.sh
+++ b/cli/scripts/install-cli.sh
@@ -8,14 +8,14 @@
# env:
# DIFY_VERSION Dify release tag to install difyctl from (e.g. 1.14.2). Primary key.
# DIFYCTL_VERSION difyctl version pin (used only when DIFY_VERSION is unset).
-# DIFYCTL_PREFIX install dir (default $HOME/.local); binary -> $PREFIX/bin/difyctl
+# DIFYCTL_PREFIX install prefix (default $HOME/.local); binary -> $PREFIX/bin/difyctl
+# DIFYCTL_INSTALL_DIR the bin folder itself (wins over DIFYCTL_PREFIX); binary -> $DIR/difyctl
# DIFYCTL_REPO release source repo (default langgenius/dify)
# GITHUB_TOKEN GitHub token (or GH_TOKEN) to raise the API rate limit to 5000/hour.
# requires: curl, uname, sort -V, and sha256sum or shasum.
set -eu
REPO="${DIFYCTL_REPO:-langgenius/dify}"
-PREFIX="${DIFYCTL_PREFIX:-${HOME}/.local}"
DIFY_VERSION="${DIFY_VERSION:-}"
DIFYCTL_VERSION="${DIFYCTL_VERSION:-}"
GH_AUTH="${GITHUB_TOKEN:-${GH_TOKEN:-}}"
@@ -28,6 +28,27 @@ err() { printf '%s\n' "install-cli: $*" >&2; }
die() { err "$*"; rm -f "$FETCH_ERR_FILE"; exit 1; }
need() { command -v "$1" >/dev/null 2>&1 || die "$1 is required"; }
re_escape() { printf '%s' "$1" | sed 's/[][\\.^$*+?(){}|/]/\\&/g'; }
+# print_skill_hint BIN: the hint names a v2 command, so a binary without it (any v1 build) gets none.
+print_skill_hint() {
+ "$1" install skills --help >/dev/null 2>&1 || return 0
+ printf '%s\n' 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'
+}
+
+# DIFYCTL_INSTALL_DIR names the bin folder itself; DIFYCTL_PREFIX the folder above it.
+bin_dir_for() {
+ printf '%s' "${DIFYCTL_INSTALL_DIR:-${DIFYCTL_PREFIX:-${HOME}/.local}/bin}"
+}
+
+# install_binary SRC DEST: stage the copy next to DEST, then rename it over DEST, so a
+# running difyctl keeps its old file and DEST is never half written.
+install_binary() {
+ _stage="$(dirname "$2")/.difyctl.install.$$"
+ if cp "$1" "$_stage" && chmod 0755 "$_stage" && mv -f "$_stage" "$2"; then
+ return 0
+ fi
+ rm -f "$_stage"
+ die "cannot write $2"
+}
detect_target() {
case "$(uname -s)" in
@@ -219,19 +240,17 @@ main() {
printf '%s\n' "$_sumline" | $HASH -c -
) || die "checksum mismatch for ${asset}"
- bin_dir="${PREFIX}/bin"
+ bin_dir=$(bin_dir_for)
mkdir -p "$bin_dir"
target_bin="${bin_dir}/difyctl"
- cp "${tmp}/${asset}" "$target_bin"
- chmod +x "$target_bin"
+ install_binary "${tmp}/${asset}" "$target_bin"
printf '\ndifyctl v%s installed (from Dify %s): %s\n' "$version" "$DIFY_TAG" "$target_bin"
case ":${PATH}:" in
*":${bin_dir}:"*)
- "$target_bin" version >/dev/null 2>&1 \
- && printf 'verify: run "difyctl version"\n' \
- || err "binary present but failed to execute; check ${target_bin}"
+ printf 'verify: run "difyctl version"\n'
+ print_skill_hint "$target_bin"
;;
*)
printf '\n%s is not on your PATH. Add this to your shell profile:\n' "$bin_dir"
diff --git a/cli/scripts/install-cli.test.ts b/cli/scripts/install-cli.test.ts
index c07e2b431d2..f69739069f8 100644
--- a/cli/scripts/install-cli.test.ts
+++ b/cli/scripts/install-cli.test.ts
@@ -1,5 +1,5 @@
import { execFileSync, spawnSync } from 'node:child_process'
-import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { chmodSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { fileURLToPath } from 'node:url'
@@ -400,3 +400,102 @@ describe('install-cli fetch_json (real, fake curl on PATH)', () => {
).not.toContain('Authorization')
})
})
+
+describe('install-cli.sh install location', () => {
+ const where = (env: Record<string, string>) =>
+ runLib('bin_dir_for', { DIFYCTL_PREFIX: '', DIFYCTL_INSTALL_DIR: '', HOME: '/home/u', ...env })
+ .stdout
+
+ it('defaults to ~/.local/bin', () => {
+ expect(where({})).toBe('/home/u/.local/bin')
+ })
+
+ it('puts the binary under <DIFYCTL_PREFIX>/bin', () => {
+ expect(where({ DIFYCTL_PREFIX: '/opt/dify' })).toBe('/opt/dify/bin')
+ })
+
+ it('takes DIFYCTL_INSTALL_DIR as the bin folder itself, over DIFYCTL_PREFIX', () => {
+ expect(where({ DIFYCTL_PREFIX: '/opt/dify', DIFYCTL_INSTALL_DIR: '/usr/local/bin' })).toBe(
+ '/usr/local/bin',
+ )
+ })
+})
+
+describe('install-cli.sh install_binary', () => {
+ it('replaces the binary through a rename, leaving no staged file behind', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-install-'))
+ try {
+ const src = join(dir, 'new')
+ const dest = join(dir, 'bin-difyctl')
+ writeFileSync(src, 'new build')
+ writeFileSync(dest, 'old build')
+ const r = runLib(`install_binary "${src}" "${dest}"`)
+ expect(r.code).toBe(0)
+ expect(readFileSync(dest, 'utf8')).toBe('new build')
+ expect(execFileSync('ls', ['-A', dir], { encoding: 'utf8' }).trim().split('\n')).toEqual([
+ 'bin-difyctl',
+ 'new',
+ ])
+ // Windows filesystems have no executable bit to check.
+ if (process.platform !== 'win32') {
+ expect(
+ execFileSync('sh', ['-c', `test -x "${dest}" && echo yes`], { encoding: 'utf8' }),
+ ).toBe('yes\n')
+ }
+ } finally {
+ rmSync(dir, { recursive: true, force: true })
+ }
+ })
+
+ // A shared install must stay readable by other users, whatever the installer's umask.
+ it.skipIf(process.platform === 'win32')(
+ 'installs a 0600 source as mode 0755 under umask 077',
+ () => {
+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-install-'))
+ try {
+ const src = join(dir, 'new')
+ const dest = join(dir, 'bin-difyctl')
+ writeFileSync(src, 'new build', { mode: 0o600 })
+ const r = runLib(`umask 077; install_binary "${src}" "${dest}"`)
+ expect(r.code).toBe(0)
+ expect(statSync(dest).mode & 0o777).toBe(0o755)
+ } finally {
+ rmSync(dir, { recursive: true, force: true })
+ }
+ },
+ )
+
+ it('dies without touching the old binary when the folder is not writable', () => {
+ const r = runLib('install_binary /nonexistent/src /nonexistent-dir/difyctl')
+ expect(r.code).not.toBe(0)
+ expect(r.stderr).toMatch(/cannot write \/nonexistent-dir\/difyctl/)
+ })
+})
+
+// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".
+describe.skipIf(process.platform === 'win32')('install-cli.sh print_skill_hint', () => {
+ const fakeBins = [
+ 'd="$(mktemp -d)"',
+ 'printf \'#!/bin/sh\\n[ "$*" = "install skills --help" ]\\n\' > "$d/v2"',
+ 'printf \'#!/bin/sh\\necho "unknown command: $*" >&2\\nexit 1\\n\' > "$d/v1"',
+ 'chmod 0755 "$d/v2" "$d/v1"',
+ ]
+
+ it('prints the hint for a binary that has install skills', () => {
+ const r = runLib([...fakeBins, 'print_skill_hint "$d/v2"', 'rm -rf "$d"'].join('\n'))
+ expect(r.code).toBe(0)
+ expect(r.stdout).toMatch(/difyctl install skills <skills root>/)
+ })
+
+ it('prints nothing for a binary without install skills', () => {
+ const r = runLib([...fakeBins, 'print_skill_hint "$d/v1"', 'rm -rf "$d"'].join('\n'))
+ expect(r.code).toBe(0)
+ expect(r.stdout).toBe('')
+ })
+
+ it('prints nothing when the binary cannot run', () => {
+ const r = runLib('print_skill_hint /nonexistent/difyctl')
+ expect(r.code).toBe(0)
+ expect(r.stdout).toBe('')
+ })
+})
diff --git a/cli/scripts/install-r2.ps1 b/cli/scripts/install-r2.ps1
index 44321d13fac..e3b93809e2c 100644
--- a/cli/scripts/install-r2.ps1
+++ b/cli/scripts/install-r2.ps1
@@ -2,6 +2,7 @@
# Usage: $env:DIFYCTL_R2_BASE='<BASE>'; irm https://raw.githubusercontent.com/langgenius/dify/main/cli/scripts/install-r2.ps1 | iex
# Env: DIFYCTL_R2_BASE (required), DIFYCTL_CHANNEL (default edge),
# DIFYCTL_INSTALL_DIR (default %LOCALAPPDATA%\difyctl\bin; binary written here as difyctl.exe),
+# DIFYCTL_PREFIX (the folder above the bin folder; <prefix>\bin is used when DIFYCTL_INSTALL_DIR is unset),
# DIFYCTL_VERSION (pin exact published version),
# DIFYCTL_COMMIT (pin by git commit, short or full sha; via index.json),
# DIFYCTL_R2_PREFIX (default difyctl; key root for pointer JSONs),
@@ -38,22 +39,51 @@ function Get-ChecksumTarget([string]$text, [string]$target) {
return $null
}
-# Download, sha256-verify, place. Returns nothing; throws on mismatch.
+# DIFYCTL_INSTALL_DIR names the bin folder itself; DIFYCTL_PREFIX the folder above it.
+function Resolve-BinDir {
+ if ($env:DIFYCTL_INSTALL_DIR) { return $env:DIFYCTL_INSTALL_DIR }
+ $prefix = if ($env:DIFYCTL_PREFIX) { $env:DIFYCTL_PREFIX } else { Join-Path $env:LOCALAPPDATA 'difyctl' }
+ return Join-Path $prefix 'bin'
+}
+
+# The user PATH alone: $env:PATH also holds the machine PATH, which must not be copied into it.
+function Get-PathHint([string]$Dir) {
+ return " [Environment]::SetEnvironmentVariable('PATH', `"$Dir;`" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')"
+}
+
+# The hint names a v2 command, so a binary without it (any v1 build) gets none. Under
+# Windows PowerShell 5.1 a redirected stderr line throws when errors stop, hence the catch.
+function Write-SkillHint([string]$Bin) {
+ try { & $Bin install skills --help *> $null } catch { return }
+ if ($LASTEXITCODE -ne 0) { return }
+ Write-Host 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'
+}
+
+# Download, sha256-verify, place. Returns nothing; throws on a missing or wrong checksum.
function Install-DifyctlBinary([string]$dlUrl, [string]$sha, [string]$version, [string]$channel, [string]$installDir) {
- $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ([System.IO.Path]::GetFileName($dlUrl))
- Invoke-WebRequest -Uri $dlUrl -OutFile $tmp
- $actual = (Get-FileHash -Path $tmp -Algorithm SHA256).Hash.ToLower()
- if ($actual -ne $sha.ToLower()) { throw "checksum mismatch for $dlUrl" }
+ if (-not $sha) { throw "no checksum published for $dlUrl; not installing an unverified binary" }
+ $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ('difyctl-' + [guid]::NewGuid().ToString('N') + '.exe')
+ try {
+ Invoke-WebRequest -Uri $dlUrl -OutFile $tmp
+ $actual = (Get-FileHash -Path $tmp -Algorithm SHA256).Hash.ToLower()
+ if ($actual -ne $sha.ToLower()) { throw "checksum mismatch for $dlUrl" }
- New-Item -ItemType Directory -Path $installDir -Force | Out-Null
- $dest = Join-Path $installDir 'difyctl.exe'
- try { Move-Item -Path $tmp -Destination $dest -Force }
- catch { throw "cannot replace $dest — close any running difyctl and re-run." }
+ New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+ $dest = Join-Path $installDir 'difyctl.exe'
+ try { Move-Item -Path $tmp -Destination $dest -Force }
+ catch { throw "cannot replace $dest — close any running difyctl and re-run." }
+ }
+ finally {
+ Remove-Item -Path $tmp -Force -ErrorAction SilentlyContinue
+ }
Write-Host "difyctl $version (channel $channel) installed: $dest"
if (($env:PATH -split ';') -notcontains $installDir) {
Write-Host "$installDir is not on your PATH. Add it with:"
- Write-Host " [Environment]::SetEnvironmentVariable('PATH', `"$installDir;`$env:PATH`", 'User')"
+ Write-Host (Get-PathHint $installDir)
+ }
+ else {
+ Write-SkillHint $dest
}
}
@@ -64,7 +94,7 @@ function Install-DifyctlR2 {
$channel = if ($env:DIFYCTL_CHANNEL) { $env:DIFYCTL_CHANNEL } else { 'edge' }
$prefix = if ($env:DIFYCTL_R2_PREFIX) { $env:DIFYCTL_R2_PREFIX } else { 'difyctl' }
$binPrefix = if ($env:DIFYCTL_R2_BIN_PREFIX) { $env:DIFYCTL_R2_BIN_PREFIX } else { "$prefix/bin" }
- $installDir = if ($env:DIFYCTL_INSTALL_DIR) { $env:DIFYCTL_INSTALL_DIR } else { Join-Path (Join-Path $env:LOCALAPPDATA 'difyctl') 'bin' }
+ $installDir = Resolve-BinDir
$target = 'windows-x64'
if ($env:DIFYCTL_VERSION -or $env:DIFYCTL_COMMIT) {
diff --git a/cli/scripts/install-r2.ps1.test.ts b/cli/scripts/install-r2.ps1.test.ts
index b7b983a26e0..ee9e623358d 100644
--- a/cli/scripts/install-r2.ps1.test.ts
+++ b/cli/scripts/install-r2.ps1.test.ts
@@ -1,4 +1,7 @@
import { spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { describe, expect, it } from 'vite-plus/test'
@@ -17,11 +20,14 @@ const MANIFEST = JSON.stringify({
},
})
-function pwsh(program: string): { code: number; stdout: string; stderr: string } {
+function pwsh(
+ program: string,
+ env: Record<string, string> = {},
+): { code: number; stdout: string; stderr: string } {
const full = `. '${SCRIPT}'\n${program}`
const r = spawnSync('pwsh', ['-NoProfile', '-Command', full], {
encoding: 'utf8',
- env: { ...process.env, DIFYCTL_INSTALL_LIB: '1' },
+ env: { ...process.env, DIFYCTL_INSTALL_LIB: '1', ...env },
})
return {
code: r.status ?? 1,
@@ -51,3 +57,81 @@ d('install-r2.ps1', () => {
}
})
})
+
+d('install-r2.ps1 install location, PATH hint and download', () => {
+ const where = (env: Record<string, string>) =>
+ pwsh('Write-Output (Resolve-BinDir)', {
+ DIFYCTL_PREFIX: '',
+ DIFYCTL_INSTALL_DIR: '',
+ LOCALAPPDATA: '/lad',
+ ...env,
+ }).stdout
+
+ it('defaults to %LOCALAPPDATA%\\difyctl\\bin', () => {
+ expect(where({})).toBe(join('/lad', 'difyctl', 'bin'))
+ })
+
+ it('accepts DIFYCTL_PREFIX like the GitHub installer', () => {
+ expect(where({ DIFYCTL_PREFIX: '/opt/dify' })).toBe(join('/opt/dify', 'bin'))
+ })
+
+ it('keeps DIFYCTL_INSTALL_DIR as the bin folder itself, over DIFYCTL_PREFIX', () => {
+ expect(where({ DIFYCTL_PREFIX: '/opt/dify', DIFYCTL_INSTALL_DIR: '/custom/bin' })).toBe(
+ '/custom/bin',
+ )
+ })
+
+ it('the PATH command adds to the user PATH, not the whole session PATH', () => {
+ const hint = pwsh(`Write-Output (Get-PathHint 'C:\\dify\\bin')`).stdout
+ expect(hint).toContain(
+ `"C:\\dify\\bin;" + [Environment]::GetEnvironmentVariable('PATH', 'User')`,
+ )
+ expect(hint).not.toContain('$env:PATH')
+ })
+
+ it('stops before downloading when the checksum is missing', () => {
+ const r = pwsh(
+ "function Invoke-WebRequest { throw 'must not download' }\n" +
+ "try { Install-DifyctlBinary 'https://x/difyctl.exe' '' '1.0.0' 'edge' '/tmp/none' } " +
+ 'catch { Write-Output $_.Exception.Message }',
+ )
+ expect(r.stdout).toMatch(/^no checksum published for https:\/\/x\/difyctl\.exe/)
+ })
+
+ it('downloads to a unique temp file, not one named after the asset', () => {
+ const r = pwsh(
+ 'function Invoke-WebRequest { param($Uri, $OutFile) Write-Output "OUT=$OutFile"; Set-Content -Path $OutFile -Value x }\n' +
+ "try { Install-DifyctlBinary 'https://x/difyctl.exe' 'deadbeef' '1.0.0' 'edge' '/tmp/none' } " +
+ 'catch { Write-Output $_.Exception.Message }',
+ )
+ expect(r.stdout).toMatch(/OUT=.*difyctl-[0-9a-f]{32}\.exe\n/)
+ expect(r.stdout).toMatch(/checksum mismatch/)
+ })
+})
+
+// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".
+// The fakes are shell scripts, so this runs where pwsh runs outside Windows.
+describe.skipIf(!hasPwsh || process.platform === 'win32')('install-r2.ps1 Write-SkillHint', () => {
+ const hint = (bin: string) => pwsh(`Write-SkillHint '${bin}'`)
+
+ it('prints the hint for a binary that has install skills, and stays quiet otherwise', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-hint-'))
+ try {
+ const v2 = join(dir, 'v2')
+ const v1 = join(dir, 'v1')
+ writeFileSync(v2, '#!/bin/sh\n[ "$*" = "install skills --help" ]\n', { mode: 0o755 })
+ writeFileSync(v1, '#!/bin/sh\necho "unknown command: $*" >&2\nexit 1\n', { mode: 0o755 })
+ expect(hint(v2)).toMatchObject({
+ code: 0,
+ stdout: expect.stringContaining('difyctl install skills <skills root>'),
+ })
+ expect(hint(v1)).toMatchObject({ code: 0, stdout: '' })
+ } finally {
+ rmSync(dir, { recursive: true, force: true })
+ }
+ })
+
+ it('prints nothing when the binary cannot run', () => {
+ expect(hint('/nonexistent/difyctl')).toMatchObject({ code: 0, stdout: '' })
+ })
+})
diff --git a/cli/scripts/install-r2.sh b/cli/scripts/install-r2.sh
index ffb4d980429..d8b549a7bb5 100755
--- a/cli/scripts/install-r2.sh
+++ b/cli/scripts/install-r2.sh
@@ -6,6 +6,7 @@
# DIFYCTL_R2_BASE (required) R2 public base, e.g. https://pub-….r2.dev
# DIFYCTL_CHANNEL (default edge)
# DIFYCTL_INSTALL_DIR (default $HOME/.local/bin) directory the binary is written to as <dir>/difyctl
+# DIFYCTL_PREFIX the folder above the bin folder; <prefix>/bin is used when DIFYCTL_INSTALL_DIR is unset
# DIFYCTL_VERSION pin an exact published version (e.g. 0.1.0-edge.ce4af868)
# DIFYCTL_COMMIT pin by git commit (short or full sha); resolved via index.json
# DIFYCTL_R2_PREFIX (default difyctl) key root for pointer JSONs
@@ -21,12 +22,33 @@ trap 'rm -f "$tmp_m" "${tmp_c:-}" "${tmp_b:-}"' EXIT INT TERM
err() { printf '%s\n' "install-r2: $*" >&2; }
die() { err "$*"; exit 1; }
need() { command -v "$1" >/dev/null 2>&1 || die "$1 is required"; }
+# print_skill_hint BIN: the hint names a v2 command, so a binary without it (any v1 build) gets none.
+print_skill_hint() {
+ "$1" install skills --help >/dev/null 2>&1 || return 0
+ printf '%s\n' 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'
+}
+
+# DIFYCTL_INSTALL_DIR names the bin folder itself; DIFYCTL_PREFIX the folder above it.
+bin_dir_for() {
+ printf '%s' "${DIFYCTL_INSTALL_DIR:-${DIFYCTL_PREFIX:-${HOME}/.local}/bin}"
+}
+
+# install_binary SRC DEST: stage the copy next to DEST, then rename it over DEST, so a
+# running difyctl keeps its old file and DEST is never half written.
+install_binary() {
+ _stage="$(dirname "$2")/.difyctl.install.$$"
+ if cp "$1" "$_stage" && chmod 0755 "$_stage" && mv -f "$_stage" "$2"; then
+ return 0
+ fi
+ rm -f "$_stage"
+ die "cannot write $2"
+}
detect_target() {
case "$(uname -s)" in
Linux*) _os=linux ;;
Darwin*) _os=darwin ;;
- *) die "unsupported OS: $(uname -s) (use install.ps1 on Windows)" ;;
+ *) die "unsupported OS: $(uname -s) (use install-r2.ps1 on Windows)" ;;
esac
case "$(uname -m)" in
x86_64|amd64) _arch=x64 ;;
@@ -90,12 +112,11 @@ fetch_verify_install() {
sha256_check "$tmp_b" "$2"
mkdir -p "$install_dir"
- chmod +x "$tmp_b"
- mv "$tmp_b" "${install_dir}/difyctl" 2>/dev/null || { cp "$tmp_b" "${install_dir}/difyctl"; rm -f "$tmp_b"; }
+ install_binary "$tmp_b" "${install_dir}/difyctl"
printf 'difyctl %s (channel %s) installed: %s\n' "$3" "$4" "${install_dir}/difyctl"
case ":${PATH}:" in
- *":${install_dir}:"*) ;;
+ *":${install_dir}:"*) print_skill_hint "${install_dir}/difyctl" ;;
*) printf 'note: add %s to your PATH\n' "$install_dir" ;;
esac
}
@@ -147,7 +168,7 @@ install_main() {
channel="${DIFYCTL_CHANNEL:-edge}"
prefix="${DIFYCTL_R2_PREFIX:-difyctl}"
bin_prefix="${DIFYCTL_R2_BIN_PREFIX:-${prefix}/bin}"
- install_dir="${DIFYCTL_INSTALL_DIR:-${HOME}/.local/bin}"
+ install_dir="$(bin_dir_for)"
target="$(detect_target)"
if [ -n "${DIFYCTL_VERSION:-}" ] || [ -n "${DIFYCTL_COMMIT:-}" ]; then
diff --git a/cli/scripts/install-r2.test.ts b/cli/scripts/install-r2.test.ts
index d6875524433..026cf5f0f0c 100644
--- a/cli/scripts/install-r2.test.ts
+++ b/cli/scripts/install-r2.test.ts
@@ -146,3 +146,77 @@ describe('install-r2 version/commit pin', () => {
expect(r.stdout).toBe('deadbeef\tdifyctl-v0.1.0-edge.ce4af868-linux-x64')
})
})
+
+describe('install-r2.sh install location', () => {
+ const where = (env: Record<string, string>) =>
+ lib('bin_dir_for', { DIFYCTL_PREFIX: '', DIFYCTL_INSTALL_DIR: '', HOME: '/home/u', ...env })
+ .stdout
+
+ it('defaults to ~/.local/bin', () => {
+ expect(where({})).toBe('/home/u/.local/bin')
+ })
+
+ it('accepts DIFYCTL_PREFIX like the GitHub installer', () => {
+ expect(where({ DIFYCTL_PREFIX: '/opt/dify' })).toBe('/opt/dify/bin')
+ })
+
+ it('keeps DIFYCTL_INSTALL_DIR as the bin folder itself, over DIFYCTL_PREFIX', () => {
+ expect(where({ DIFYCTL_PREFIX: '/opt/dify', DIFYCTL_INSTALL_DIR: '/usr/local/bin' })).toBe(
+ '/usr/local/bin',
+ )
+ })
+})
+
+it.skipIf(process.platform === 'win32')(
+ 'install-r2.sh points Windows users at install-r2.ps1',
+ () => {
+ const r = lib('uname() { printf MINGW64_NT; }; detect_target')
+ expect(r.code).not.toBe(0)
+ expect(r.stderr).toMatch(/use install-r2\.ps1 on Windows/)
+ },
+)
+
+describe.skipIf(process.platform === 'win32')('install-r2.sh install_binary', () => {
+ it('installs a 0600 temp file as mode 0755 next to and then over the target', () => {
+ const r = lib(
+ [
+ 'd="$(mktemp -d)"',
+ 'src="$(mktemp)"; chmod 0600 "$src"; printf new > "$src"',
+ 'printf old > "$d/difyctl"',
+ 'install_binary "$src" "$d/difyctl"',
+ 'ls -l "$d/difyctl" | cut -c1-10; cat "$d/difyctl"; echo; ls -A "$d"',
+ 'rm -rf "$d" "$src"',
+ ].join('\n'),
+ )
+ expect(r.code).toBe(0)
+ expect(r.stdout.split('\n')).toEqual(['-rwxr-xr-x', 'new', 'difyctl'])
+ })
+})
+
+// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".
+describe.skipIf(process.platform === 'win32')('install-r2.sh print_skill_hint', () => {
+ const fakeBins = [
+ 'd="$(mktemp -d)"',
+ 'printf \'#!/bin/sh\\n[ "$*" = "install skills --help" ]\\n\' > "$d/v2"',
+ 'printf \'#!/bin/sh\\necho "unknown command: $*" >&2\\nexit 1\\n\' > "$d/v1"',
+ 'chmod 0755 "$d/v2" "$d/v1"',
+ ]
+
+ it('prints the hint for a binary that has install skills', () => {
+ const r = lib([...fakeBins, 'print_skill_hint "$d/v2"', 'rm -rf "$d"'].join('\n'))
+ expect(r.code).toBe(0)
+ expect(r.stdout).toMatch(/difyctl install skills <skills root>/)
+ })
+
+ it('prints nothing for a binary without install skills', () => {
+ const r = lib([...fakeBins, 'print_skill_hint "$d/v1"', 'rm -rf "$d"'].join('\n'))
+ expect(r.code).toBe(0)
+ expect(r.stdout).toBe('')
+ })
+
+ it('prints nothing when the binary cannot run', () => {
+ const r = lib('print_skill_hint /nonexistent/difyctl')
+ expect(r.code).toBe(0)
+ expect(r.stdout).toBe('')
+ })
+})
diff --git a/cli/scripts/install.ps1 b/cli/scripts/install.ps1
index 19a114eff10..3fae747b150 100644
--- a/cli/scripts/install.ps1
+++ b/cli/scripts/install.ps1
@@ -7,7 +7,8 @@
# env:
# DIFY_VERSION Dify release tag to install difyctl from (e.g. 1.14.2). Primary key.
# DIFYCTL_VERSION difyctl version pin (used only when DIFY_VERSION is unset).
-# DIFYCTL_PREFIX install dir (default $env:LOCALAPPDATA\difyctl)
+# DIFYCTL_PREFIX install prefix (default $env:LOCALAPPDATA\difyctl); binary -> <prefix>\bin\difyctl.exe
+# DIFYCTL_INSTALL_DIR the bin folder itself (wins over DIFYCTL_PREFIX); binary -> <dir>\difyctl.exe
# DIFYCTL_REPO release source repo (default langgenius/dify)
# GITHUB_TOKEN GitHub token (or GH_TOKEN) sent as a bearer to raise the API
# rate limit from 60 to 5000 requests/hour (useful in CI).
@@ -17,7 +18,6 @@ $ErrorActionPreference = 'Stop'
$repo = if ($env:DIFYCTL_REPO) { $env:DIFYCTL_REPO } else { 'langgenius/dify' }
$difyVersion = $env:DIFY_VERSION
$difyctlVersion = $env:DIFYCTL_VERSION
-$prefix = if ($env:DIFYCTL_PREFIX) { $env:DIFYCTL_PREFIX } else { Join-Path $env:LOCALAPPDATA 'difyctl' }
$target = 'windows-x64'
$apiBase = "https://api.github.com/repos/$repo"
$dlBase = "https://github.com/$repo/releases/download"
@@ -115,6 +115,26 @@ function Resolve-Release {
}
}
+# DIFYCTL_INSTALL_DIR names the bin folder itself; DIFYCTL_PREFIX the folder above it.
+function Resolve-BinDir {
+ if ($env:DIFYCTL_INSTALL_DIR) { return $env:DIFYCTL_INSTALL_DIR }
+ $prefix = if ($env:DIFYCTL_PREFIX) { $env:DIFYCTL_PREFIX } else { Join-Path $env:LOCALAPPDATA 'difyctl' }
+ return Join-Path $prefix 'bin'
+}
+
+# The user PATH alone: $env:PATH also holds the machine PATH, which must not be copied into it.
+function Get-PathHint([string]$Dir) {
+ return " [Environment]::SetEnvironmentVariable('PATH', `"$Dir;`" + [Environment]::GetEnvironmentVariable('PATH', 'User'), 'User')"
+}
+
+# The hint names a v2 command, so a binary without it (any v1 build) gets none. Under
+# Windows PowerShell 5.1 a redirected stderr line throws when errors stop, hence the catch.
+function Write-SkillHint([string]$Bin) {
+ try { & $Bin install skills --help *> $null } catch { return }
+ if ($LASTEXITCODE -ne 0) { return }
+ Write-Host 'AI agents: run `difyctl install skills <skills root>` after each install or upgrade; the skill ships inside the binary.'
+}
+
function Invoke-Main {
$release = Resolve-Release
$difyTag = $release.tag_name
@@ -143,20 +163,30 @@ function Invoke-Main {
$actual = (Get-FileHash -Path $assetPath -Algorithm SHA256).Hash.ToLower()
if ($actual -ne $expected.ToLower()) { throw "checksum mismatch for $assetName" }
- $binDir = Join-Path $prefix 'bin'
+ $binDir = Resolve-BinDir
New-Item -ItemType Directory -Path $binDir -Force | Out-Null
$targetBin = Join-Path $binDir 'difyctl.exe'
- Copy-Item -Path $assetPath -Destination $targetBin -Force
+ # Stage next to the target, then rename over it, so difyctl.exe is never half written.
+ $stage = Join-Path $binDir ('.difyctl.install.' + [guid]::NewGuid().ToString('N') + '.exe')
+ try {
+ Copy-Item -Path $assetPath -Destination $stage -Force
+ Move-Item -Path $stage -Destination $targetBin -Force
+ }
+ catch {
+ Remove-Item -Path $stage -Force -ErrorAction SilentlyContinue
+ throw "cannot replace $targetBin — close any running difyctl and re-run."
+ }
Write-Host ""
Write-Host "difyctl v$ver installed (from Dify $difyTag): $targetBin"
if (($env:PATH -split ';') -notcontains $binDir) {
Write-Host ""
Write-Host "$binDir is not on your PATH. Add it with:"
- Write-Host " [Environment]::SetEnvironmentVariable('PATH', `"$binDir;`$env:PATH`", 'User')"
+ Write-Host (Get-PathHint $binDir)
}
else {
Write-Host 'verify: run "difyctl version"'
+ Write-SkillHint $targetBin
}
}
finally {
diff --git a/cli/scripts/install.ps1.test.ts b/cli/scripts/install.ps1.test.ts
index a75f4defbea..e56e2b5467b 100644
--- a/cli/scripts/install.ps1.test.ts
+++ b/cli/scripts/install.ps1.test.ts
@@ -1,4 +1,7 @@
import { spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { describe, expect, it } from 'vite-plus/test'
@@ -295,3 +298,62 @@ describe.skipIf(!PWSH)('install.ps1 rate limit', () => {
expect(r.stderr).not.toContain('not found')
})
})
+
+describe.skipIf(!PWSH)('install.ps1 install location and PATH hint', () => {
+ const where = (env: Record<string, string>) =>
+ runPwsh('Write-Output (Resolve-BinDir)', {
+ DIFYCTL_PREFIX: '',
+ DIFYCTL_INSTALL_DIR: '',
+ LOCALAPPDATA: '/lad',
+ ...env,
+ }).stdout
+
+ it('defaults to %LOCALAPPDATA%\\difyctl\\bin', () => {
+ expect(where({})).toBe(join('/lad', 'difyctl', 'bin'))
+ })
+
+ it('puts the binary under <DIFYCTL_PREFIX>\\bin', () => {
+ expect(where({ DIFYCTL_PREFIX: '/opt/dify' })).toBe(join('/opt/dify', 'bin'))
+ })
+
+ it('takes DIFYCTL_INSTALL_DIR as the bin folder itself, over DIFYCTL_PREFIX', () => {
+ expect(where({ DIFYCTL_PREFIX: '/opt/dify', DIFYCTL_INSTALL_DIR: '/custom/bin' })).toBe(
+ '/custom/bin',
+ )
+ })
+
+ it('the PATH command adds to the user PATH, not the whole session PATH', () => {
+ const hint = runPwsh(`Write-Output (Get-PathHint 'C:\\dify\\bin')`).stdout
+ expect(hint).toContain(
+ `"C:\\dify\\bin;" + [Environment]::GetEnvironmentVariable('PATH', 'User')`,
+ )
+ expect(hint).not.toContain('$env:PATH')
+ })
+})
+
+// A v2 binary answers `install skills --help`; a v1 one exits 1 with "unknown command".
+// The fakes are shell scripts, so this runs where pwsh runs outside Windows.
+describe.skipIf(!PWSH || process.platform === 'win32')('install.ps1 Write-SkillHint', () => {
+ const hint = (bin: string) => runPwsh(`Write-SkillHint '${bin}'`)
+
+ it('prints the hint for a binary that has install skills, and stays quiet otherwise', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-hint-'))
+ try {
+ const v2 = join(dir, 'v2')
+ const v1 = join(dir, 'v1')
+ writeFileSync(v2, '#!/bin/sh\n[ "$*" = "install skills --help" ]\n', { mode: 0o755 })
+ writeFileSync(v1, '#!/bin/sh\necho "unknown command: $*" >&2\nexit 1\n', { mode: 0o755 })
+ expect(hint(v2)).toMatchObject({
+ code: 0,
+ stdout: expect.stringContaining('difyctl install skills <skills root>'),
+ })
+ expect(hint(v1)).toMatchObject({ code: 0, stdout: '' })
+ } finally {
+ rmSync(dir, { recursive: true, force: true })
+ }
+ })
+
+ it('prints nothing when the binary cannot run', () => {
+ expect(hint('/nonexistent/difyctl')).toMatchObject({ code: 0, stdout: '' })
+ })
+})
diff --git a/cli/scripts/release-build.sh b/cli/scripts/release-build.sh
index 31e22c2526f..7dc320de929 100755
--- a/cli/scripts/release-build.sh
+++ b/cli/scripts/release-build.sh
@@ -41,6 +41,10 @@ DIFYCTL_BUILD_DATE="${DIFYCTL_BUILD_DATE:-$(date -u +%Y-%m-%dT%H:%M:%SZ)}"
[[ "$CLI_VERSION" != "undefined" ]] || die "CLI_VERSION could not be derived from package.json"
+repo_root="$(cd "${cli_root}/.." && pwd)"
+skill_dir="${repo_root}/skills/difyctl"
+[[ -f "${skill_dir}/SKILL.md" ]] || die "skill not found: ${skill_dir}"
+
[[ -f "$entry" ]] || die "entry not found: $entry"
rm -rf "$out_dir"
@@ -53,6 +57,7 @@ defines=(
"--define" "__DIFYCTL_CHANNEL__=\"${DIFYCTL_CHANNEL}\""
"--define" "__DIFYCTL_COMMIT__=\"${DIFYCTL_COMMIT}\""
"--define" "__DIFYCTL_BUILD_DATE__=\"${DIFYCTL_BUILD_DATE}\""
+ "--define" "__DIFYCTL_COMPILED__=true"
)
# Targets and asset names come from cli/package.json `difyctl.release` via
@@ -60,12 +65,15 @@ defines=(
while IFS=$'\t' read -r bun_target asset_target _exe; do
out="${out_dir}/$(naming asset "$CLI_VERSION" "$asset_target")"
log::info "compiling ${asset_target} -> $(basename "$out")..."
- bun build "$entry" \
+ # Run from the repo root: --asset paths are embedded relative to the cwd, which gives
+ # the skill its difyctl/ prefix.
+ (cd "$repo_root" && bun build "$entry" \
+ --asset "$skill_dir" \
--target="$bun_target" \
--compile \
--minify \
"${defines[@]}" \
- --outfile="$out" >/dev/null
+ --outfile="$out") >/dev/null
done < <(naming targets)
log::info "built $(find "$out_dir" -type f | wc -l | tr -d ' ') binaries:"
diff --git a/cli/scripts/release-smoke.sh b/cli/scripts/release-smoke.sh
new file mode 100755
index 00000000000..93f7e7da196
--- /dev/null
+++ b/cli/scripts/release-smoke.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# scripts/release-smoke.sh <bin> — run a built binary on this runner and check that
+# `install skills` writes exactly the skill tree in skills/difyctl.
+
+set -euo pipefail
+
+_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+source "${_dir}/lib/common.sh"
+
+bin="${1:?usage: release-smoke.sh <bin>}"
+skill_dir="$(cd "$(cli::root)/.." && pwd)/skills/difyctl"
+out="$(mktemp -d)"
+trap 'rm -rf "$out"' EXIT
+
+"$bin" version
+"$bin" install skills "$out"
+diff -r "${out}/difyctl" "$skill_dir"
diff --git a/cli/scripts/run-smoke.ts b/cli/scripts/run-smoke.ts
index 958c9fe3153..f7249fa10e0 100644
--- a/cli/scripts/run-smoke.ts
+++ b/cli/scripts/run-smoke.ts
@@ -1,7 +1,7 @@
#!/usr/bin/env -S bun
// scripts/run-smoke.ts — five checks against a running Dify server (or mock),
-// through `bun bin/dev.js`. DIFY_SERVER, DIFY_TOKEN, DIFY_CONFIG_DIR, and
-// DIFY_CACHE_DIR are read from the environment and passed through unchanged.
+// through `bun bin/dev.js`. DIFY_SERVER, DIFY_TOKEN and DIFY_CONFIG_DIR are
+// read from the environment and passed through unchanged.
import { execFileSync, spawnSync } from 'node:child_process'
import { ExitCode } from '../src/errors/codes.js'
diff --git a/cli/src/auth/pending-login.ts b/cli/src/auth/pending-login.ts
new file mode 100644
index 00000000000..cfcc5842d56
--- /dev/null
+++ b/cli/src/auth/pending-login.ts
@@ -0,0 +1,40 @@
+import type { CommandContext } from '@/plugins/base'
+import { join } from 'node:path'
+import { z } from 'zod'
+import { env } from '@/plugins/env'
+import { io } from '@/plugins/io'
+import { localFile } from '@/store/local-file'
+
+export const PENDING_FILE_NAME = 'login-pending.yml'
+
+const PENDING_SCHEMA = z.object({
+ server: z.string(),
+ insecure: z.boolean(),
+ no_keyring: z.boolean(),
+ device_code: z.string(),
+})
+export type Pending = z.infer<typeof PENDING_SCHEMA>
+
+export type PendingLoginStore = Readonly<{
+ read: () => Promise<Pending | null>
+ save: (pending: Pending) => Promise<void>
+ clear: () => Promise<void>
+ /** Clear only while the file still holds `deviceCode`: a newer login's code survives. */
+ clearIf: (deviceCode: string) => Promise<void>
+}>
+
+/** The device code a `login --no-wait` saved for `login --resume` to finish. */
+export async function pendingLoginStore(ctx: CommandContext): Promise<PendingLoginStore> {
+ const { configDir } = await ctx.get(env)
+ const file = localFile(
+ join(configDir, PENDING_FILE_NAME),
+ PENDING_SCHEMA,
+ (await ctx.get(io)).notice,
+ )
+ return {
+ read: file.read,
+ save: file.write,
+ clear: file.remove,
+ clearIf: (deviceCode) => file.removeIf((pending) => pending.device_code === deviceCode),
+ }
+}
diff --git a/cli/src/call/execute.test.ts b/cli/src/call/execute.test.ts
index 130ecaac1d6..889fd6fcff4 100644
--- a/cli/src/call/execute.test.ts
+++ b/cli/src/call/execute.test.ts
@@ -148,10 +148,28 @@ it('a paused run is exit 0 with status suspended and the server hints', async ()
expect(await (await w.ctx.get(commands)).run()).toBe(0)
expect(JSON.parse(w.io.outBuf())).toMatchObject({
status: 'suspended',
+ run_id: 'wf-run-hitl-1',
hints: [{ op: 'submit.run.form', input: { form_token: 'ft-hitl-1', action: 'submit' } }],
})
})
+it('a form submit prints the hint to follow the run', async () => {
+ const w = await world([
+ 'submit',
+ 'run',
+ 'form',
+ '--input',
+ '{"app_id":"app-2","form_token":"ft-hitl-1","action":"submit","inputs":{"name":"Bob"}}',
+ ])
+ expect(await (await w.ctx.get(commands)).run()).toBe(0)
+ expect(JSON.parse(w.io.outBuf()).hints).toEqual([
+ expect.objectContaining({
+ op: 'get.run.event',
+ input: { app_id: 'app-2', task_id: 'wf-run-hitl-1', continue_on_pause: false },
+ }),
+ ])
+})
+
it('a stale catalog is refreshed once and the op is retried', async () => {
const w = await world(['help'])
await (await w.ctx.get(commands)).run()
diff --git a/cli/src/call/execute.ts b/cli/src/call/execute.ts
index d8eeea35205..3e03d98e2d3 100644
--- a/cli/src/call/execute.ts
+++ b/cli/src/call/execute.ts
@@ -7,17 +7,17 @@ import { unsupportedFlags } from '@/call/flags'
import { applyPins, loadInput, resolveFileRefs } from '@/call/input'
import { rendererFor } from '@/call/render/index'
import { buildRequest } from '@/call/request'
-import { validateInput } from '@/call/validate'
import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { runSignal } from '@/plugins/commands/cancel'
-import { helpHint, Outcome } from '@/plugins/commands/command'
+import { assertValidInput, Outcome } from '@/plugins/commands/command'
import { http } from '@/plugins/http'
import { io } from '@/plugins/io'
import { session } from '@/plugins/session'
import { KIND } from '@/protocol/kinds'
-import { spacedId } from '@/protocol/op-id'
+import { commandWords } from '@/protocol/op-id'
import { PIN } from '@/protocol/pins'
+import { flagToken } from '@/util/flag-name'
/** One catalog operation, its call flags, and the fields typed as flags of their own. */
export type CallRequest = Readonly<{
@@ -36,7 +36,7 @@ function assertSupportedFlags(kind: string, flags: CallFlags): void {
if (refused !== undefined) {
throw new BaseError({
code: ErrorCode.UsageInvalidFlag,
- message: `--${refused} is not supported by ${kind} operations`,
+ message: `${flagToken(refused)} is not supported by ${kind} operations`,
})
}
// --only filters the events --stream emits; on its own it filters nothing.
@@ -51,18 +51,6 @@ async function readAll(stream: NodeJS.ReadableStream): Promise<string> {
return text
}
-function assertValidInput(op: CatalogOp, opId: string, input: Record<string, unknown>): void {
- const details = validateInput(op.input, input)
- if (details.length === 0) return
- throw new BaseError({
- code: ErrorCode.InputInvalid,
- message: `invalid input for "${opId}"`,
- hint: helpHint(spacedId(opId)),
- details: [...details],
- schema: op.input,
- })
-}
-
export async function executeCall(req: CallRequest, ctx: CommandContext): Promise<Outcome> {
assertSupportedFlags(req.op.kind, req.flags)
@@ -75,7 +63,7 @@ export async function executeCall(req: CallRequest, ctx: CommandContext): Promis
const fields = await resolveFileRefs(req.fields, req.op.input, source)
const workspaceId = await (await ctx.get(session)).workspaceId()
const body = applyPins({ ...whole, ...fields }, req.op.input, { [PIN.Workspace]: workspaceId })
- assertValidInput(req.op, req.id, body)
+ assertValidInput({ command: commandWords(req.id), schema: req.op.input, input: body })
if (req.op.deprecated) out.notice(`${DEPRECATED_NOTICE}: ${req.id}`)
diff --git a/cli/src/call/fold.test.ts b/cli/src/call/fold.test.ts
index d0aac2c0e07..69cdc284c15 100644
--- a/cli/src/call/fold.test.ts
+++ b/cli/src/call/fold.test.ts
@@ -91,3 +91,18 @@ it('copies server hints from a pause and suspends; a pause without hints is stil
])
expect(bare.result).toEqual({ status: 'suspended', text: { answer: '' }, hints: [] })
})
+
+it('keeps the run id from any event, even one it has no handler for', () => {
+ const { result, code } = run([
+ ['workflow_started', { workflow_run_id: 'run-1', data: { id: 'run-1' } }],
+ ['human_input_required', { workflow_run_id: 'run-1', hints: [] }],
+ ['workflow_paused', { workflow_run_id: 'run-1' }],
+ ])
+ expect(result).toMatchObject({ status: 'suspended', run_id: 'run-1' })
+ expect(code).toBe(0)
+})
+
+it('ignores a run id that is not a string', () => {
+ const { result } = run([['some_future_event', { workflow_run_id: 42 }]])
+ expect(result).not.toHaveProperty('run_id')
+})
diff --git a/cli/src/call/fold.ts b/cli/src/call/fold.ts
index 2c1a359ad1a..85266b3ebca 100644
--- a/cli/src/call/fold.ts
+++ b/cli/src/call/fold.ts
@@ -1,15 +1,15 @@
import type { ExitCodeValue } from '@/errors/codes'
import type { FoldResult } from '@/protocol/fold'
import { ExitCode } from '@/errors/codes'
-import { FOLD_STATUS, FOLD_TABLE } from '@/protocol/fold'
+import { FOLD_STATUS, FOLD_TABLE, foldAnyEvent } from '@/protocol/fold'
export function newFoldResult(): FoldResult {
return { status: FOLD_STATUS.Incomplete, text: { answer: '' }, hints: [] }
}
export function foldEvent(result: FoldResult, name: string, event: Record<string, unknown>): void {
- const handler = FOLD_TABLE[name]
- if (handler !== undefined) handler(result, event)
+ foldAnyEvent(result, event)
+ FOLD_TABLE[name]?.(result, event)
}
export function finishFold(result: FoldResult): FoldResult {
diff --git a/cli/src/call/input.ts b/cli/src/call/input.ts
index 607fe9a7626..ea68ff9c930 100644
--- a/cli/src/call/input.ts
+++ b/cli/src/call/input.ts
@@ -1,7 +1,9 @@
import type { JsonSchema } from '@/plugins/catalog'
import { inputInvalid } from '@/call/errors'
+import { CALL_FLAG } from '@/call/flags'
import { errorMessage } from '@/errors/message'
import { isScalar, propertiesOf, shapeOf } from '@/protocol/shape'
+import { flagToken } from '@/util/flag-name'
import { isRecord } from '@/util/is-record'
export type InputSource = {
@@ -18,8 +20,7 @@ type Referenced = Readonly<{ text: string; source: string }>
const FILE_PREFIX = '@'
const STDIN_MARKER = '-'
const STDIN_SOURCE = `${FILE_PREFIX}${STDIN_MARKER}`
-const FLAG_PREFIX = '--'
-const INLINE_SOURCE = '--input'
+const INLINE_SOURCE = flagToken(CALL_FLAG.Input)
const STDIN_LABEL = 'stdin'
export function parseJsonValue(raw: string, source: string): unknown {
@@ -69,7 +70,7 @@ export async function resolveFileRefs(
if (typeof value !== 'string' || !value.startsWith(FILE_PREFIX)) continue
if (isScalar(shapeOf(property))) continue
const { text } = await readRef(value, src)
- resolved[name] = parseJsonValue(text, `${FLAG_PREFIX}${name}`)
+ resolved[name] = parseJsonValue(text, flagToken(name))
}
return resolved
}
diff --git a/cli/src/call/render/file.ts b/cli/src/call/render/file.ts
index a23e7e4e812..cb21ca294e5 100644
--- a/cli/src/call/render/file.ts
+++ b/cli/src/call/render/file.ts
@@ -1,12 +1,18 @@
import type { Renderer } from './index'
import { writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import { unknownError } from '@/errors/base'
+import { join, posix } from 'node:path'
+import { CALL_FLAG } from '@/call/flags'
+import { BaseError, unknownError } from '@/errors/base'
+import { ErrorCode } from '@/errors/codes'
import { renderJson } from './object'
const CONTENT_DISPOSITION_HEADER = 'content-disposition'
const CONTENT_TYPE_HEADER = 'content-type'
const UNKNOWN_EXTENSION = 'bin'
+const EEXIST = 'EEXIST'
+// A name the server picked never replaces a file; a path the caller named does.
+const CREATE_ONLY = 'wx'
+const CREATE_OR_REPLACE = 'w'
const EXTENSIONS: Readonly<Record<string, string>> = {
'application/json': 'json',
@@ -21,10 +27,18 @@ const EXTENSIONS: Readonly<Record<string, string>> = {
const QUOTED_FILENAME = /filename="([^"]+)"/
const BARE_FILENAME = /filename=([^;]+)/
+const NOT_A_FILE_NAME: readonly string[] = ['', '.', '..']
+
+// Only the last part of the server's name is used, so the file stays in the folder.
+function baseName(raw: string | undefined): string | undefined {
+ if (raw === undefined) return undefined
+ const name = posix.basename(raw.replaceAll('\\', '/'))
+ return NOT_A_FILE_NAME.includes(name) ? undefined : name
+}
function filenameFromContentDisposition(value: string | null): string | undefined {
if (value === null) return undefined
- return QUOTED_FILENAME.exec(value)?.[1] ?? BARE_FILENAME.exec(value)?.[1]?.trim()
+ return baseName(QUOTED_FILENAME.exec(value)?.[1] ?? BARE_FILENAME.exec(value)?.[1]?.trim())
}
function extensionOf(contentType: string | null): string {
@@ -39,10 +53,18 @@ export const fileRenderer: Renderer = async (res, io, options, opId) => {
filenameFromContentDisposition(res.headers.get(CONTENT_DISPOSITION_HEADER)) ??
`${opId}.${extensionOf(contentType)}`
const path = options.output ?? join(process.cwd(), filename)
+ const flag = options.output === undefined ? CREATE_ONLY : CREATE_OR_REPLACE
try {
- await writeFile(path, bytes)
+ await writeFile(path, bytes, { flag })
} catch (cause) {
+ if ((cause as NodeJS.ErrnoException).code === EEXIST)
+ throw new BaseError({
+ code: ErrorCode.UsageMissingArg,
+ message: `${path} already exists; not overwriting it`,
+ hint: `pass --${CALL_FLAG.Output} <path> to choose where to save it`,
+ cause,
+ })
throw unknownError(`failed to write file: ${path}`, cause)
}
diff --git a/cli/src/call/render/render.test.ts b/cli/src/call/render/render.test.ts
index 40fa8f253ab..dafa530f272 100644
--- a/cli/src/call/render/render.test.ts
+++ b/cli/src/call/render/render.test.ts
@@ -1,6 +1,6 @@
import type { CallFlags } from '@/call/flags'
import { Buffer } from 'node:buffer'
-import { mkdtempSync, readFileSync } from 'node:fs'
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { expect, it } from 'vite-plus/test'
@@ -138,3 +138,81 @@ it('file names an unnamed download after the op and its content type', async ()
process.chdir(cwd)
}
})
+
+it.each([
+ ['../../escape.txt', 'escape.txt'],
+ ['/etc/passwd', 'passwd'],
+ ['..\\..\\win.txt', 'win.txt'],
+ ['..', `${OP_ID}.txt`],
+ ['dir/', 'dir'],
+])('file keeps only the base name of the server filename %s', async (sent, kept) => {
+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-file-'))
+ const cwd = process.cwd()
+ process.chdir(dir)
+ const here = process.cwd()
+ try {
+ const r = render(
+ 'file',
+ new Response('x', {
+ headers: {
+ 'content-type': 'text/plain',
+ 'content-disposition': `attachment; filename="${sent}"`,
+ },
+ }),
+ )
+ await r.code
+ expect(JSON.parse(r.buf.outBuf())).toMatchObject({ path: join(here, kept) })
+ expect(readFileSync(join(here, kept), 'utf8')).toBe('x')
+ } finally {
+ process.chdir(cwd)
+ }
+})
+
+it('file refuses to overwrite an existing file it named itself, and keeps the old bytes', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-file-'))
+ const cwd = process.cwd()
+ process.chdir(dir)
+ const here = join(process.cwd(), 'r.txt')
+ writeFileSync(here, 'old')
+ try {
+ const r = render(
+ 'file',
+ new Response('new', {
+ headers: {
+ 'content-type': 'text/plain',
+ 'content-disposition': 'attachment; filename="r.txt"',
+ },
+ }),
+ )
+ await expect(r.code).rejects.toMatchObject({
+ code: 'usage_missing_arg',
+ message: `${here} already exists; not overwriting it`,
+ hint: 'pass --output <path> to choose where to save it',
+ })
+ expect(readFileSync(here, 'utf8')).toBe('old')
+ expect(r.buf.outBuf()).toBe('')
+ } finally {
+ process.chdir(cwd)
+ }
+})
+
+it('file overwrites an existing file when --output names it', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-file-'))
+ const out = join(dir, 'z.txt')
+ writeFileSync(out, 'old')
+ const r = render('file', new Response('new', { headers: { 'content-type': 'text/plain' } }), {
+ output: out,
+ })
+ await r.code
+ expect(readFileSync(out, 'utf8')).toBe('new')
+})
+
+it('file reports other write failures as a failed write, not an existing file', async () => {
+ const dir = mkdtempSync(join(tmpdir(), 'difyctl-file-'))
+ const out = join(dir, 'missing', 'z.txt')
+ const r = render('file', new Response('x'), { output: out })
+ await expect(r.code).rejects.toMatchObject({
+ code: 'unknown',
+ message: `failed to write file: ${out}`,
+ })
+})
diff --git a/cli/src/call/validate.ts b/cli/src/call/validate.ts
index 0036e8274f8..4f4ccacdee5 100644
--- a/cli/src/call/validate.ts
+++ b/cli/src/call/validate.ts
@@ -21,17 +21,21 @@ function compile(schema: JsonSchema): ValidateFunction {
return validate
}
-function locFor(error: ErrorObject): (string | number)[] {
- const loc = error.instancePath.split('/').filter(Boolean)
- if (error.keyword === 'required') {
- const missingProperty = (error.params as { missingProperty?: string }).missingProperty
- if (missingProperty !== undefined) loc.push(missingProperty)
- }
- return loc
+const INSTANCE_PATH_SEPARATOR = '/'
+
+// Errors that name a field: the ajv param holding the name, and the message to show.
+const FIELD_ERRORS: Readonly<Record<string, Readonly<{ param: string; msg: string }>>> = {
+ required: { param: 'missingProperty', msg: 'required' },
+ additionalProperties: { param: 'additionalProperty', msg: 'unknown field' },
}
function toDetail(error: ErrorObject): ValidationDetail {
- return { type: error.keyword, loc: locFor(error), msg: error.message ?? error.keyword }
+ const reading = FIELD_ERRORS[error.keyword]
+ const loc: (string | number)[] = error.instancePath.split(INSTANCE_PATH_SEPARATOR).filter(Boolean)
+ const named =
+ reading === undefined ? undefined : (error.params as Record<string, unknown>)[reading.param]
+ if (typeof named === 'string') loc.push(named)
+ return { type: error.keyword, loc, msg: reading?.msg ?? error.message ?? error.keyword }
}
export function validateInput(schema: JsonSchema, input: unknown): readonly ValidationDetail[] {
diff --git a/cli/src/commands/get/skills/index.ts b/cli/src/commands/get/skills/index.ts
deleted file mode 100644
index 2fc0c8f27f4..00000000000
--- a/cli/src/commands/get/skills/index.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-import { z } from 'zod'
-import { Command } from '@/plugins/commands/command'
-import { loadSkills } from '@/skills/collection'
-import { FROM_FIELD, openSource } from '@/skills/source'
-
-const INPUT = z.object({ from: FROM_FIELD })
-
-export default class SkillsList extends Command<typeof INPUT> {
- static override summary = 'List the skills in the collection'
- static override input = INPUT
-
- async run(input: z.infer<typeof INPUT>) {
- const skills = await loadSkills(await openSource(input.from))
- return { skills: skills.map(({ name, description }) => ({ name, description })) }
- }
-}
diff --git a/cli/src/commands/install/skills/index.test.ts b/cli/src/commands/install/skills/index.test.ts
index 17cf0630cd5..67c3b840e13 100644
--- a/cli/src/commands/install/skills/index.test.ts
+++ b/cli/src/commands/install/skills/index.test.ts
@@ -1,23 +1,20 @@
import type { TestWorld } from '@test/fixtures/kernel'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
-import { fileURLToPath } from 'node:url'
import { testContext } from '@test/fixtures/kernel'
import { afterEach, expect, it } from 'vite-plus/test'
import { commands } from '@/plugins/commands'
-const REPO_SKILLS = fileURLToPath(new URL('../../../../../skills', import.meta.url))
-
const worlds: TestWorld[] = []
afterEach(async () => {
for (const w of worlds.splice(0)) await w.stop()
})
-it('writes the repo skills into the given skills root', async () => {
+it('writes the difyctl skill into the given skills root', async () => {
const seed = await testContext({ login: false })
worlds.push(seed)
const dir = join(seed.dir, 'target')
- const argv = ['install', 'skills', dir, '--from', REPO_SKILLS]
+ const argv = ['install', 'skills', dir]
const w = await testContext({ login: false, argv, reuseDirOf: seed })
worlds.push(w)
expect(await (await w.ctx.get(commands)).run()).toBe(0)
diff --git a/cli/src/commands/install/skills/index.ts b/cli/src/commands/install/skills/index.ts
index cb9a62ee6eb..95bc788f1a1 100644
--- a/cli/src/commands/install/skills/index.ts
+++ b/cli/src/commands/install/skills/index.ts
@@ -1,8 +1,7 @@
import { resolve } from 'node:path'
import { z } from 'zod'
import { Command } from '@/plugins/commands/command'
-import { loadSkills } from '@/skills/collection'
-import { installSkills, selectSkills } from '@/skills/install'
+import { installSkill } from '@/skills/install'
import { FROM_FIELD, openSource } from '@/skills/source'
const INPUT = z.object({
@@ -10,26 +9,19 @@ const INPUT = z.object({
.string()
.min(1)
.describe("The agent's skills root: the folder that holds one subfolder per skill"),
- skill: z
- .array(z.string())
- .default([])
- .describe('Skill to install (repeatable); default: the whole collection'),
from: FROM_FIELD,
})
export default class SkillsInstall extends Command<typeof INPUT> {
- static override summary = 'Write skills from the collection into a skills root'
+ static override summary = 'Write the difyctl skill into a skills root'
static override effect = 'write' as const
static override input = INPUT
static override positional = ['dir'] as const
static override examples = [
- { title: 'Install every skill for Claude Code', input: { dir: '~/.claude/skills' } },
- { title: 'Install one skill for Codex', input: { dir: '~/.codex/skills', skill: ['difyctl'] } },
+ { title: 'Install the skill for Claude Code', input: { dir: '~/.claude/skills' } },
]
async run(input: z.infer<typeof INPUT>) {
- const source = await openSource(input.from)
- const skills = selectSkills(await loadSkills(source), input.skill)
- return { wrote: await installSkills(resolve(input.dir), skills, source) }
+ return { wrote: await installSkill(resolve(input.dir), await openSource(input.from)) }
}
}
diff --git a/cli/src/commands/login/index.test.ts b/cli/src/commands/login/index.test.ts
index 46f2bc32966..a62cbb7991e 100644
--- a/cli/src/commands/login/index.test.ts
+++ b/cli/src/commands/login/index.test.ts
@@ -1,6 +1,10 @@
import type { TestWorld } from '@test/fixtures/kernel'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
import { testContext } from '@test/fixtures/kernel'
import { afterEach, expect, it } from 'vite-plus/test'
+import { PENDING_FILE_NAME } from '@/auth/pending-login'
+import { Context } from '@/kernel/context'
import { commands } from '@/plugins/commands'
import { session } from '@/plugins/session'
import { token } from '@/plugins/token'
@@ -95,3 +99,163 @@ it('falls back to the external-SSO subject email when there is no account', asyn
expect(login?.email).toBe('[email protected]')
expect(login?.account).toBeNull()
})
+
+it('resume with no pending login reports the saved login', async () => {
+ const w = await testContext({ login: true, argv: ['login', '--resume'] })
+ worlds.push(w)
+ expect(await (await w.ctx.get(commands)).run()).toBe(0)
+ expect(JSON.parse(w.io.outBuf())).toMatchObject({
+ server: w.mock.url,
+ email: 'me@x',
+ workspace_id: 'ws-1',
+ })
+})
+
+it('resume with no pending login and no saved login is not_logged_in', async () => {
+ const w = await testContext({ login: false, argv: ['login', '--resume'] })
+ worlds.push(w)
+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({
+ code: 'not_logged_in',
+ message: `not logged in: no login saved in ${w.dir}; DIFY_CONFIG_DIR picks this folder`,
+ })
+})
+
+it('resume with no pending login and the token gone is not_logged_in', async () => {
+ const w = await testContext({ login: true, argv: ['login', '--resume'] })
+ worlds.push(w)
+ const fresh = new Context()
+ const login = await (await fresh.get(session)).require()
+ await (await fresh.get(token)).remove(login)
+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({ code: 'not_logged_in' })
+})
+
+it('resume under an env login reports the env login', async () => {
+ const w = await testContext({ login: false, env: true, argv: ['login', '--resume'] })
+ worlds.push(w)
+ expect(await (await w.ctx.get(commands)).run()).toBe(0)
+ expect(JSON.parse(w.io.outBuf())).toMatchObject({ server: w.mock.url, email: 'env' })
+})
+
+it('a new login drops a pending --no-wait login', async () => {
+ const seed = await testContext({ login: false })
+ worlds.push(seed)
+ const pendingFile = join(seed.dir, PENDING_FILE_NAME)
+ writeFileSync(
+ pendingFile,
+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: stale\n`,
+ )
+ const w = await testContext({
+ login: false,
+ argv: ['login', '--server', seed.mock.url, '--no-browser', '--no-keyring', '--insecure'],
+ reuseDirOf: seed,
+ })
+ worlds.push(w)
+ expect(await (await w.ctx.get(commands)).run()).toBe(0)
+ expect(existsSync(pendingFile)).toBe(false)
+})
+
+it.each([[[]], [['--server', ' ']]])(
+ 'refuses to start without a server, keeping a pending login',
+ async (flags) => {
+ const seed = await testContext({ login: false })
+ worlds.push(seed)
+ const pendingPath = join(seed.dir, PENDING_FILE_NAME)
+ writeFileSync(
+ pendingPath,
+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: kept\n`,
+ )
+ const w = await testContext({
+ login: false,
+ argv: ['login', '--no-wait', ...flags],
+ reuseDirOf: seed,
+ })
+ worlds.push(w)
+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({
+ code: 'usage_missing_arg',
+ hint: 'ask the user which server; Dify Cloud is https://cloud.dify.ai',
+ })
+ expect(existsSync(pendingPath)).toBe(true)
+ },
+)
+
+it('keeps a pending login when the new --server is rejected', async () => {
+ const seed = await testContext({ login: false })
+ worlds.push(seed)
+ const pendingPath = join(seed.dir, PENDING_FILE_NAME)
+ writeFileSync(
+ pendingPath,
+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: kept\n`,
+ )
+ const w = await testContext({
+ login: false,
+ argv: ['login', '--server', 'http://plain.example.com', '--no-wait'],
+ reuseDirOf: seed,
+ })
+ worlds.push(w)
+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({
+ code: 'usage_invalid_flag',
+ })
+ expect(existsSync(pendingPath)).toBe(true)
+})
+
+it('resume under an env login refuses a pending login before polling', async () => {
+ const seed = await testContext({ login: false, env: true })
+ worlds.push(seed)
+ const pendingPath = join(seed.dir, PENDING_FILE_NAME)
+ writeFileSync(
+ pendingPath,
+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: kept\n`,
+ )
+ const w = await testContext({
+ login: false,
+ env: true,
+ argv: ['login', '--resume'],
+ reuseDirOf: seed,
+ })
+ worlds.push(w)
+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({
+ code: 'usage_invalid_flag',
+ message: 'unset DIFY_TOKEN to log in interactively',
+ })
+ expect(existsSync(pendingPath)).toBe(true)
+})
+
+it.each(['happy', 'denied', 'expired'] as const)(
+ 'resume (%s) leaves a pending login another process saved meanwhile',
+ async (scenario) => {
+ const seed = await testContext({ login: false })
+ worlds.push(seed)
+ const pendingPath = join(seed.dir, PENDING_FILE_NAME)
+ const pendingFor = (code: string) =>
+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: ${code}\n`
+ writeFileSync(pendingPath, pendingFor('dc-1'))
+ seed.mock.setScenario(scenario)
+ seed.mock.onDeviceTokenPoll(() => writeFileSync(pendingPath, pendingFor('dc-2')))
+ const w = await testContext({ login: false, argv: ['login', '--resume'], reuseDirOf: seed })
+ worlds.push(w)
+
+ await (await w.ctx.get(commands)).run().catch(() => undefined)
+
+ expect(readFileSync(pendingPath, 'utf8')).toContain('device_code: dc-2')
+ },
+)
+
+it.each(['happy', 'denied', 'expired'] as const)(
+ 'resume (%s) clears its own pending login',
+ async (scenario) => {
+ const seed = await testContext({ login: false })
+ worlds.push(seed)
+ const pendingPath = join(seed.dir, PENDING_FILE_NAME)
+ writeFileSync(
+ pendingPath,
+ `server: ${seed.mock.url}\ninsecure: true\nno_keyring: true\ndevice_code: dc-1\n`,
+ )
+ seed.mock.setScenario(scenario)
+ const w = await testContext({ login: false, argv: ['login', '--resume'], reuseDirOf: seed })
+ worlds.push(w)
+
+ await (await w.ctx.get(commands)).run().catch(() => undefined)
+
+ expect(existsSync(pendingPath)).toBe(false)
+ },
+)
diff --git a/cli/src/commands/login/index.ts b/cli/src/commands/login/index.ts
index f061a734177..c8a2e2a270c 100644
--- a/cli/src/commands/login/index.ts
+++ b/cli/src/commands/login/index.ts
@@ -1,24 +1,28 @@
import type { PollSuccess } from '@/auth/device-api'
+import type { Pending, PendingLoginStore } from '@/auth/pending-login'
import type { CommandContext } from '@/plugins/base'
+import type { Login as SavedLogin } from '@/plugins/session'
import { hostname } from 'node:os'
-import { join } from 'node:path'
import { z } from 'zod'
import { deviceApi } from '@/auth/device-api'
import { awaitAuthorization, pollAuthorization, realClock } from '@/auth/device-flow'
import { assertNotEnvLogin, revokeAndClearSession } from '@/auth/logout'
+import { pendingLoginStore } from '@/auth/pending-login'
import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { Command } from '@/plugins/commands/command'
-import { env } from '@/plugins/env'
import { io } from '@/plugins/io'
import { session } from '@/plugins/session'
-import { token } from '@/plugins/token'
-import { YamlStore } from '@/store/store'
+import { token, TOKENS_FILE_NAME } from '@/plugins/token'
import { decideOpen, OpenDecision, openUrl, realEnv } from '@/util/browser'
-import { DEFAULT_HOST, resolveHost, validateVerificationURI } from '@/util/host'
+import { resolveHost, validateVerificationURI } from '@/util/host'
const INPUT = z.object({
- server: z.string().default(DEFAULT_HOST).describe('Dify server base URL'),
+ server: z
+ .string()
+ .trim()
+ .optional()
+ .describe('Dify server base URL. Required to start a login; there is no default'),
no_browser: z
.boolean()
.default(false)
@@ -27,7 +31,7 @@ const INPUT = z.object({
.boolean()
.default(false)
.describe(
- 'Keep the token in tokens.yml under the config dir instead of the OS keyring. Use in a sandbox, with DIFY_CONFIG_DIR on persistent storage',
+ `Keep the token in ${TOKENS_FILE_NAME} under the config dir instead of the OS keyring. Use in a sandbox, with DIFY_CONFIG_DIR on persistent storage`,
),
insecure: z
.boolean()
@@ -41,24 +45,17 @@ const INPUT = z.object({
.boolean()
.default(false)
.describe(
- 'Check a login started with --no-wait once. Prints status pending until the user approves',
+ 'Check a login started with --no-wait once. Prints status pending until the user approves. With no pending login, prints the saved login, or fails with not_logged_in',
),
})
-const PENDING_FILE_NAME = 'login-pending.yml'
const PENDING_STATUS = 'pending'
-const PENDING_SCHEMA = z.object({
- server: z.string(),
- insecure: z.boolean(),
- no_keyring: z.boolean(),
- device_code: z.string(),
-})
-type Pending = z.infer<typeof PENDING_SCHEMA>
-const NO_PENDING_MESSAGE = 'no pending login; start one with login --no-wait'
const FINAL_POLL_ERRORS: readonly string[] = [ErrorCode.AuthExpired, ErrorCode.AccessDenied]
const ENV_LOGIN_MESSAGE = 'unset DIFY_TOKEN to log in interactively'
const NO_EMAIL_MESSAGE = 'login response carries no account or subject email'
+const NO_SERVER_MESSAGE = 'pass --server <url>: the Dify server to log in to'
+const NO_SERVER_HINT = 'ask the user which server; Dify Cloud is https://cloud.dify.ai'
// A present-but-empty email is the same as absent: neither account.email nor
// subject_email is meaningful until it has a value.
@@ -68,39 +65,44 @@ function meaningfulEmail(value: string | undefined): string | undefined {
export default class Login extends Command<typeof INPUT> {
static override summary =
- 'Log in via the OAuth device flow. Blocks until approval: run it in the background, never cancel it'
+ 'Log in via the OAuth device flow. Agents: use --no-wait, then --resume after the user approves'
static override effect = 'write' as const
static override input = INPUT
static override examples = [
{
- title: 'Agent: run in the background, relay the url and code to the user, do not cancel',
- input: { server: 'https://dify.example.com', no_browser: true },
+ title: 'Agent: start without waiting, give the user the url and code, then end the turn',
+ input: { server: 'https://dify.example.com', no_browser: true, no_wait: true },
},
{
title: 'Agent in a sandbox: add --no-keyring and point DIFY_CONFIG_DIR at persistent storage',
- input: { server: 'https://dify.example.com', no_browser: true, no_keyring: true },
- },
- {
- title: 'Agent that cannot keep a process alive: start without waiting',
- input: { server: 'https://dify.example.com', no_browser: true, no_wait: true },
+ input: {
+ server: 'https://dify.example.com',
+ no_browser: true,
+ no_wait: true,
+ no_keyring: true,
+ },
},
{
- title: 'Then, after the user approves, finish the login (repeat while status is pending)',
+ title: 'Finish a --no-wait login once the user says they approved',
input: { resume: true },
},
]
async run(input: z.infer<typeof INPUT>, ctx: CommandContext) {
+ const pendingLogin = await pendingLoginStore(ctx)
+ if (input.resume) return resume(ctx, pendingLogin)
+
const sessionService = await ctx.get(session)
assertNotEnvLogin(sessionService.fromEnv, ENV_LOGIN_MESSAGE)
-
- const { configDir } = await ctx.get(env)
- const pendingStore = new YamlStore(join(configDir, PENDING_FILE_NAME))
- if (input.resume) return resume(ctx, pendingStore)
+ if (input.server === undefined || input.server === '')
+ throw new BaseError({
+ code: ErrorCode.UsageMissingArg,
+ message: NO_SERVER_MESSAGE,
+ hint: NO_SERVER_HINT,
+ })
const server = resolveHost({ raw: input.server, insecure: input.insecure })
const streams = await ctx.get(io)
-
const current = await sessionService.current()
if (current !== null) {
await revokeAndClearSession(ctx, current)
@@ -125,7 +127,7 @@ export default class Login extends Command<typeof INPUT> {
device_code: code.device_code,
}
if (input.no_wait) {
- await pendingStore.setTyped(pending)
+ await pendingLogin.save(pending)
return {
status: PENDING_STATUS,
verification_uri: code.verification_uri,
@@ -134,28 +136,47 @@ export default class Login extends Command<typeof INPUT> {
}
}
+ await pendingLogin.clear()
const success = await awaitAuthorization(api, code, { clock: realClock() })
return finish(ctx, pending, success)
}
}
-async function resume(ctx: CommandContext, pendingStore: YamlStore) {
- const parsed = PENDING_SCHEMA.safeParse(await pendingStore.getTyped<unknown>())
- if (!parsed.success) {
- throw new BaseError({ code: ErrorCode.UsageInvalidFlag, message: NO_PENDING_MESSAGE })
+function loginReport(login: SavedLogin) {
+ return {
+ server: login.server,
+ email: login.email,
+ account: login.account,
+ workspace_id: login.workspaceId,
+ }
+}
+
+// `get` throws not_logged_in when the saved login's token is gone from the store.
+async function assertTokenSaved(ctx: CommandContext): Promise<void> {
+ await (await ctx.get(token)).get()
+}
+
+async function resume(ctx: CommandContext, pendingLogin: PendingLoginStore) {
+ const sessionService = await ctx.get(session)
+ const pending = await pendingLogin.read()
+ if (pending === null) {
+ const current = await sessionService.require()
+ await assertTokenSaved(ctx)
+ return loginReport(current)
}
- const pending = parsed.data
+ assertNotEnvLogin(sessionService.fromEnv, ENV_LOGIN_MESSAGE)
const api = deviceApi(pending.server, { insecure: pending.insecure })
let success: PollSuccess | undefined
try {
success = await pollAuthorization(api, pending.device_code, { clock: realClock() })
} catch (err) {
- if (err instanceof BaseError && FINAL_POLL_ERRORS.includes(err.code)) await pendingStore.rm()
+ if (err instanceof BaseError && FINAL_POLL_ERRORS.includes(err.code))
+ await pendingLogin.clearIf(pending.device_code)
throw err
}
if (success === undefined) return { status: PENDING_STATUS }
const result = await finish(ctx, pending, success)
- await pendingStore.rm()
+ await pendingLogin.clearIf(pending.device_code)
return result
}
@@ -168,7 +189,7 @@ async function finish(ctx: CommandContext, pending: Pending, success: PollSucces
throw new BaseError({ code: ErrorCode.ServerError, message: NO_EMAIL_MESSAGE })
}
- const login = {
+ const login: SavedLogin = {
server: pending.server,
email,
account: success.account ?? null,
@@ -179,11 +200,5 @@ async function finish(ctx: CommandContext, pending: Pending, success: PollSucces
await sessionService.save(login)
await tokenService.write(login, success.token)
-
- return {
- server: pending.server,
- email,
- account: login.account,
- workspace_id: login.workspaceId,
- }
+ return loginReport(login)
}
diff --git a/cli/src/commands/logout/index.test.ts b/cli/src/commands/logout/index.test.ts
index 7f33606f9de..7646ddeab76 100644
--- a/cli/src/commands/logout/index.test.ts
+++ b/cli/src/commands/logout/index.test.ts
@@ -1,8 +1,9 @@
import type { TestWorld } from '@test/fixtures/kernel'
-import { existsSync, readdirSync } from 'node:fs'
+import { existsSync, readdirSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { testContext } from '@test/fixtures/kernel'
import { afterEach, expect, it } from 'vite-plus/test'
+import { PENDING_FILE_NAME } from '@/auth/pending-login'
import { Context } from '@/kernel/context'
import { commands } from '@/plugins/commands'
import { session } from '@/plugins/session'
@@ -32,6 +33,24 @@ it('revokes the session on the server and clears local state', async () => {
})
})
+it('drops a pending --no-wait login', async () => {
+ const w = await testContext({ login: true, argv: ['logout'] })
+ worlds.push(w)
+ const pendingFile = join(w.dir, PENDING_FILE_NAME)
+ writeFileSync(pendingFile, 'device_code: stale\n')
+ expect(await (await w.ctx.get(commands)).run()).toBe(0)
+ expect(existsSync(pendingFile)).toBe(false)
+})
+
+it('drops a pending --no-wait login when nobody is logged in', async () => {
+ const w = await testContext({ login: false, argv: ['logout'] })
+ worlds.push(w)
+ const pendingFile = join(w.dir, PENDING_FILE_NAME)
+ writeFileSync(pendingFile, 'device_code: stale\n')
+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({ code: 'not_logged_in' })
+ expect(existsSync(pendingFile)).toBe(false)
+})
+
it('still clears local state and reports a failed server revoke', async () => {
const w = await testContext({ login: true, argv: ['logout'] })
worlds.push(w)
@@ -54,3 +73,14 @@ it('refuses under an env login', async () => {
message: 'nothing to log out: the login comes from DIFY_TOKEN',
})
})
+
+it('refuses under an env login without dropping a pending interactive login', async () => {
+ const w = await testContext({ login: false, env: true, argv: ['logout'] })
+ worlds.push(w)
+ const pendingFile = join(w.dir, PENDING_FILE_NAME)
+ writeFileSync(pendingFile, 'device_code: dc-1\n')
+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({
+ code: 'usage_invalid_flag',
+ })
+ expect(existsSync(pendingFile)).toBe(true)
+})
diff --git a/cli/src/commands/logout/index.ts b/cli/src/commands/logout/index.ts
index 74d8691524b..20166d3f42b 100644
--- a/cli/src/commands/logout/index.ts
+++ b/cli/src/commands/logout/index.ts
@@ -1,6 +1,7 @@
import type { CommandContext } from '@/plugins/base'
import { z } from 'zod'
import { assertNotEnvLogin, revokeAndClearSession } from '@/auth/logout'
+import { pendingLoginStore } from '@/auth/pending-login'
import { Command } from '@/plugins/commands/command'
import { session } from '@/plugins/session'
@@ -15,9 +16,10 @@ export default class Logout extends Command<typeof INPUT> {
async run(_input: z.infer<typeof INPUT>, ctx: CommandContext) {
const sessionService = await ctx.get(session)
- const login = await sessionService.require()
+ // Refuse before touching anything: an env login must leave a pending interactive login alone.
assertNotEnvLogin(sessionService.fromEnv, ENV_LOGOUT_MESSAGE)
-
+ await (await pendingLoginStore(ctx)).clear()
+ const login = await sessionService.require()
await revokeAndClearSession(ctx, login)
return { logged_out: true, server: login.server }
diff --git a/cli/src/commands/tree.generated.ts b/cli/src/commands/tree.generated.ts
index 53e89bf67a0..b0de87cb267 100644
--- a/cli/src/commands/tree.generated.ts
+++ b/cli/src/commands/tree.generated.ts
@@ -4,7 +4,6 @@
import type { CommandTree } from '@/plugins/commands/registry'
import DeleteCache from '@/commands/delete/cache/index'
import GetConfig from '@/commands/get/config/index'
-import GetSkills from '@/commands/get/skills/index'
import InstallSkills from '@/commands/install/skills/index'
import Login from '@/commands/login/index'
import Logout from '@/commands/logout/index'
@@ -23,7 +22,6 @@ export const commandTree: CommandTree = {
get: {
subcommands: {
config: { command: GetConfig, subcommands: {} },
- skills: { command: GetSkills, subcommands: {} },
},
},
install: {
diff --git a/cli/src/commands/use/workspace/index.test.ts b/cli/src/commands/use/workspace/index.test.ts
index c12953eadb1..26b131b567f 100644
--- a/cli/src/commands/use/workspace/index.test.ts
+++ b/cli/src/commands/use/workspace/index.test.ts
@@ -1,6 +1,8 @@
import type { TestWorld } from '@test/fixtures/kernel'
+import type { BaseError } from '@/errors/base'
import { testContext } from '@test/fixtures/kernel'
import { afterEach, expect, it } from 'vite-plus/test'
+import { ExitCode } from '@/errors/codes'
import { commands } from '@/plugins/commands'
import { ENV } from '@/plugins/env'
import { session } from '@/plugins/session'
@@ -10,13 +12,28 @@ afterEach(async () => {
for (const w of worlds.splice(0)) await w.stop()
})
-it('pins the workspace locally without a server call', async () => {
- const w = await testContext({ login: true, argv: ['use', 'workspace', 'ws-9'] })
+it('pins a workspace the account belongs to and names it', async () => {
+ const w = await testContext({ login: true, argv: ['use', 'workspace', 'ws-2'] })
+ worlds.push(w)
+ expect(await (await w.ctx.get(commands)).run()).toBe(0)
+ expect(JSON.parse(w.io.outBuf())).toEqual({ workspace_id: 'ws-2', name: 'Other' })
+ expect(await (await w.ctx.get(session)).workspaceId()).toBe('ws-2')
+})
+
+it('describe workspace with no id shows the pinned workspace', async () => {
+ const w = await testContext({ login: true, argv: ['describe', 'workspace'] })
worlds.push(w)
expect(await (await w.ctx.get(commands)).run()).toBe(0)
- expect(JSON.parse(w.io.outBuf())).toEqual({ workspace_id: 'ws-9' })
- expect(await (await w.ctx.get(session)).workspaceId()).toBe('ws-9')
- expect(w.mock.requestCount).toBe(0)
+ expect(JSON.parse(w.io.outBuf())).toMatchObject({ id: 'ws-1', name: 'Default' })
+})
+
+it('refuses a workspace the account does not belong to and keeps the old pin', async () => {
+ const w = await testContext({ login: true, argv: ['use', 'workspace', 'ws-9'] })
+ worlds.push(w)
+ const err = await (await w.ctx.get(commands)).run().catch((e: unknown) => e)
+ expect(err).toMatchObject({ message: 'workspace not found' })
+ expect((err as BaseError).exit()).toBe(ExitCode.Generic)
+ expect(await (await w.ctx.get(session)).workspaceId()).toBe('ws-1')
})
it('refuses under an env login and without a login', async () => {
diff --git a/cli/src/commands/use/workspace/index.ts b/cli/src/commands/use/workspace/index.ts
index 4a09d4fb18f..62f19f7ad61 100644
--- a/cli/src/commands/use/workspace/index.ts
+++ b/cli/src/commands/use/workspace/index.ts
@@ -1,19 +1,27 @@
import type { CommandContext } from '@/plugins/base'
import { z } from 'zod'
import { assertNotEnvLogin } from '@/auth/logout'
+import { readLocalFile } from '@/call/files'
+import { parseJsonBody } from '@/call/json-body'
+import { buildRequest } from '@/call/request'
import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { Command } from '@/plugins/commands/command'
import { env } from '@/plugins/env'
+import { http } from '@/plugins/http'
import { session } from '@/plugins/session'
const INPUT = z.object({ workspace_id: z.string().min(1) })
+const WORKSPACE = z.object({ id: z.string(), name: z.string() })
+const WORKSPACE_DESCRIBE_OP = 'describe.workspace'
const ENV_WORKSPACE_ID_MESSAGE = 'DIFY_WORKSPACE_ID is set; unset it to pin locally'
const ENV_LOGIN_MESSAGE = 'the login comes from DIFY_TOKEN; set DIFY_WORKSPACE_ID instead'
+const MALFORMED_WORKSPACE_MESSAGE = 'describe workspace response has no id and name'
export default class WorkspaceUse extends Command<typeof INPUT> {
- static override summary = 'Pin the local session to a workspace'
+ static override summary =
+ 'Pin this device to a workspace; the web console keeps its own current workspace'
static override effect = 'write' as const
static override input = INPUT
static override positional = ['workspace_id'] as const
@@ -28,8 +36,21 @@ export default class WorkspaceUse extends Command<typeof INPUT> {
const login = await sessionService.require()
assertNotEnvLogin(sessionService.fromEnv, ENV_LOGIN_MESSAGE)
- await sessionService.save({ ...login, workspaceId: input.workspace_id })
+ // Check membership first so a mistyped id is never pinned.
+ const httpService = await ctx.get(http)
+ const res = await httpService.request(async (cat) =>
+ buildRequest(
+ cat.opOrThrow(WORKSPACE_DESCRIBE_OP),
+ { workspace_id: input.workspace_id },
+ { readFile: readLocalFile },
+ ),
+ )
+ const workspace = WORKSPACE.safeParse(await parseJsonBody(res))
+ if (!workspace.success)
+ throw new BaseError({ code: ErrorCode.ServerError, message: MALFORMED_WORKSPACE_MESSAGE })
- return { workspace_id: input.workspace_id }
+ await sessionService.save({ ...login, workspaceId: workspace.data.id })
+
+ return { workspace_id: workspace.data.id, name: workspace.data.name }
}
}
diff --git a/cli/src/commands/workspace/_list/index.test.ts b/cli/src/commands/workspace/_list/index.test.ts
deleted file mode 100644
index 97e2b3ce568..00000000000
--- a/cli/src/commands/workspace/_list/index.test.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-// Skipped: `get workspace` moved out of the tree; see docs/superpowers/specs/2026-09-22-difyctl-v2-human-output-design.md
-import type { TestWorld } from '@test/fixtures/kernel'
-import type { BaseError } from '@/errors/base'
-import { testContext } from '@test/fixtures/kernel'
-import { afterEach, expect, it } from 'vite-plus/test'
-import { ExitCode } from '@/errors/codes'
-import { commands } from '@/plugins/commands'
-
-const worlds: TestWorld[] = []
-afterEach(async () => {
- for (const w of worlds.splice(0)) await w.stop()
-})
-
-it.skip('marks the pinned workspace, exactly one true', async () => {
- const w = await testContext({ login: true, argv: ['get', 'workspace'] })
- worlds.push(w)
- expect(await (await w.ctx.get(commands)).run()).toBe(0)
- const body = JSON.parse(w.io.outBuf()) as { data: Array<{ id: string; pinned: boolean }> }
- expect(body.data.length).toBeGreaterThan(0)
- const pinned = body.data.filter((row) => row.pinned)
- expect(pinned).toHaveLength(1)
- expect(pinned[0]?.id).toBe('ws-1')
-})
-
-it.skip('a response with no data array is a server error, exit 1', async () => {
- const w = await testContext({ login: true, argv: ['get', 'workspace'] })
- worlds.push(w)
- w.mock.setScenario('workspaces-malformed')
- const err = await (await w.ctx.get(commands)).run().catch((e: unknown) => e)
- expect(err).toMatchObject({
- code: 'server_error',
- message: 'get workspace response has no data array',
- })
- expect((err as BaseError).exit()).toBe(ExitCode.Generic)
- expect(w.io.outBuf()).toBe('')
-})
diff --git a/cli/src/commands/workspace/_list/index.ts b/cli/src/commands/workspace/_list/index.ts
deleted file mode 100644
index 98db0d47695..00000000000
--- a/cli/src/commands/workspace/_list/index.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import type { CommandContext } from '@/plugins/base'
-import { z } from 'zod'
-import { readLocalFile } from '@/call/files'
-import { parseJsonBody } from '@/call/json-body'
-import { buildRequest } from '@/call/request'
-import { BaseError } from '@/errors/base'
-import { ErrorCode } from '@/errors/codes'
-import { Command } from '@/plugins/commands/command'
-import { http } from '@/plugins/http'
-import { session } from '@/plugins/session'
-import { isRecord } from '@/util/is-record'
-
-const INPUT = z.object({})
-
-const WORKSPACE_LIST_OP = 'get.workspace'
-const NO_DATA_ARRAY_MESSAGE = 'get workspace response has no data array'
-
-type WorkspaceListEnvelope = {
- data: readonly Record<string, unknown>[]
-} & Record<string, unknown>
-
-function asEnvelope(body: unknown): WorkspaceListEnvelope {
- if (!isRecord(body) || !Array.isArray(body.data))
- throw new BaseError({ code: ErrorCode.ServerError, message: NO_DATA_ARRAY_MESSAGE })
- return body as WorkspaceListEnvelope
-}
-
-export default class WorkspaceList extends Command<typeof INPUT> {
- static override summary = 'List the workspaces visible to the current account'
- static override input = INPUT
-
- async run(_input: z.infer<typeof INPUT>, ctx: CommandContext) {
- const httpService = await ctx.get(http)
- const res = await httpService.request(async (cat) =>
- buildRequest(cat.opOrThrow(WORKSPACE_LIST_OP), {}, { readFile: readLocalFile }),
- )
- const envelope = asEnvelope(await parseJsonBody(res))
-
- const sessionService = await ctx.get(session)
- const pinnedId = await sessionService.workspaceId()
-
- return {
- ...envelope,
- data: envelope.data.map((row) => ({ ...row, pinned: row.id === pinnedId })),
- }
- }
-}
diff --git a/cli/src/errors/base.ts b/cli/src/errors/base.ts
index 18f313a7245..b94dba9b393 100644
--- a/cli/src/errors/base.ts
+++ b/cli/src/errors/base.ts
@@ -1,18 +1,25 @@
import type { ErrorCodeValue, ExitCodeValue } from './codes'
+import type { Hint } from '@/protocol/hint'
import { BINARY } from '@/version/info'
import { ErrorCode, exitFor } from './codes'
+export const LOC_SEPARATOR = '.'
+
export type ServerErrorDetail = {
readonly type: string
readonly loc?: (string | number)[]
readonly msg: string
}
+/** A detail the CLI reports; `field` is the input as the user typed it. */
+export type ErrorDetail = ServerErrorDetail & { readonly field?: string }
+
export type ServerErrorBody = {
readonly code?: string
readonly message: string
readonly status?: number
readonly hint?: string
+ readonly hints?: Hint[]
readonly details?: ServerErrorDetail[]
}
@@ -21,7 +28,7 @@ export type ErrorEnvelope = {
code: string
message: string
hint?: string
- details?: ServerErrorDetail[]
+ details?: ErrorDetail[]
schema?: unknown
http_status?: number
method?: string
@@ -36,14 +43,14 @@ export type BaseErrorOptions = {
readonly message: string
readonly hint?: string
readonly cause?: unknown
- readonly details?: ServerErrorDetail[]
+ readonly details?: ErrorDetail[]
readonly schema?: unknown
}
export class BaseError extends Error {
readonly code: ErrorCodeValue
readonly hint?: string
- readonly details?: ServerErrorDetail[]
+ readonly details?: ErrorDetail[]
readonly schema?: unknown
constructor(opts: BaseErrorOptions) {
@@ -116,10 +123,18 @@ export function unknownError(message: string, cause?: unknown): BaseError {
return new BaseError({ code: ErrorCode.Unknown, message, cause })
}
-export const LOGIN_HINT = `run ${BINARY} login`
+export const LOGIN_HINT = `run ${BINARY} help login`
+
+export function notLoggedInMessage(reason?: string): string {
+ return reason === undefined ? 'not logged in' : `not logged in: ${reason}`
+}
-export function notLoggedIn(): BaseError {
- return new BaseError({ code: ErrorCode.NotLoggedIn, message: 'not logged in', hint: LOGIN_HINT })
+export function notLoggedIn(reason?: string): BaseError {
+ return new BaseError({
+ code: ErrorCode.NotLoggedIn,
+ message: notLoggedInMessage(reason),
+ hint: LOGIN_HINT,
+ })
}
type HttpClientErrorOptions = BaseErrorOptions & {
diff --git a/cli/src/errors/codes.test.ts b/cli/src/errors/codes.test.ts
index df3531e0247..183509e84b7 100644
--- a/cli/src/errors/codes.test.ts
+++ b/cli/src/errors/codes.test.ts
@@ -8,7 +8,6 @@ it('maps every code to the frozen exit taxonomy', () => {
expect(exitFor(ErrorCode.UsageInvalidFlag)).toBe(ExitCode.Usage)
expect(exitFor(ErrorCode.CatalogUnavailable)).toBe(ExitCode.Catalog)
expect(exitFor(ErrorCode.UnknownOp)).toBe(ExitCode.Catalog)
- expect(exitFor(ErrorCode.ConfigSchemaUnsupported)).toBe(ExitCode.Catalog)
expect(exitFor(ErrorCode.RateLimited)).toBe(ExitCode.RateLimited)
expect(exitFor(ErrorCode.ServerError)).toBe(ExitCode.Generic)
expect(exitFor('something_from_the_future')).toBe(ExitCode.Generic)
diff --git a/cli/src/errors/codes.ts b/cli/src/errors/codes.ts
index 75aa9353e29..ec4851a9331 100644
--- a/cli/src/errors/codes.ts
+++ b/cli/src/errors/codes.ts
@@ -7,13 +7,13 @@ export const ErrorCode = {
InputInvalid: 'input_invalid',
ConfigInvalidKey: 'config_invalid_key',
ConfigInvalidValue: 'config_invalid_value',
- ConfigSchemaUnsupported: 'config_schema_unsupported',
CatalogUnavailable: 'catalog_unavailable',
UnknownOp: 'unknown_op',
NetworkConnection: 'network_connection',
RateLimited: 'rate_limited',
ServerError: 'server_error',
KeyringUnavailable: 'keyring_unavailable',
+ SkillMissing: 'skill_missing',
Unknown: 'unknown',
} as const
@@ -40,13 +40,13 @@ const CODE_TO_EXIT: Readonly<Record<ErrorCodeValue, ExitCodeValue>> = {
input_invalid: ExitCode.Usage,
config_invalid_key: ExitCode.Usage,
config_invalid_value: ExitCode.Usage,
- config_schema_unsupported: ExitCode.Catalog,
catalog_unavailable: ExitCode.Catalog,
unknown_op: ExitCode.Catalog,
network_connection: ExitCode.Generic,
rate_limited: ExitCode.RateLimited,
server_error: ExitCode.Generic,
keyring_unavailable: ExitCode.Generic,
+ skill_missing: ExitCode.Generic,
unknown: ExitCode.Generic,
}
diff --git a/cli/src/errors/format.test.ts b/cli/src/errors/format.test.ts
index 022127ba6e5..22d078b5c08 100644
--- a/cli/src/errors/format.test.ts
+++ b/cli/src/errors/format.test.ts
@@ -43,3 +43,24 @@ it('drops schema in text and shows raw_response only when verbose', () => {
)
expect(renderEnvelope(env, plain, { verbose: true })).toMatch(/raw_response: Bearer \[redacted\]/)
})
+
+it('renders each server hint as a next line with the op spelled as a command', () => {
+ const text = renderEnvelope(
+ {
+ error: {
+ code: 'dsl_invalid',
+ message: 'the DSL has errors',
+ server: {
+ message: 'the DSL has errors',
+ hints: [{ summary: 'See every problem', op: 'check.console_app.dsl', input: {} }],
+ },
+ },
+ },
+ plain,
+ { verbose: false },
+ )
+ expect(text.split('\n')).toEqual([
+ 'dsl_invalid: the DSL has errors',
+ 'next: difyctl check console_app dsl — See every problem',
+ ])
+})
diff --git a/cli/src/errors/format.ts b/cli/src/errors/format.ts
index d9f414a51da..da523f9cee8 100644
--- a/cli/src/errors/format.ts
+++ b/cli/src/errors/format.ts
@@ -1,6 +1,10 @@
-import type { ErrorEnvelope } from './base'
+import type { ErrorDetail, ErrorEnvelope } from './base'
+import type { Hint } from '@/protocol/hint'
import type { ColorScheme } from '@/sys/io/color'
+import { LOC_SEPARATOR } from '@/errors/base'
import { redactBearer } from '@/errors/sanitize'
+import { spacedId } from '@/protocol/op-id'
+import { BINARY } from '@/version/info'
const RAW_RESPONSE_HINT = 'run again with --verbose to see the raw server response'
@@ -15,6 +19,16 @@ function resolveHint(e: ErrorEnvelope['error'], opts: RenderOptions): string | u
return rawHiddenAndUnparsed ? RAW_RESPONSE_HINT : undefined
}
+function detailLine(d: ErrorDetail): string {
+ if (d.field !== undefined) return `${d.field}: ${d.msg}`
+ const loc = (d.loc ?? []).join(LOC_SEPARATOR)
+ return `${loc ? `${loc}: ` : ''}${d.msg} (${d.type})`
+}
+
+function nextLine(h: Hint, style: ColorScheme): string {
+ return `${style.magenta('next:')} ${style.cyan(`${BINARY} ${spacedId(h.op)}`)} — ${h.summary}`
+}
+
export function renderEnvelope(
env: ErrorEnvelope,
style: ColorScheme,
@@ -24,12 +38,10 @@ export function renderEnvelope(
const server = e.server
const headerCode = server?.code ?? e.code
const lines: string[] = [`${headerCode}: ${e.message}`]
- for (const d of e.details ?? server?.details ?? []) {
- const loc = (d.loc ?? []).join('.')
- lines.push(` - ${loc ? `${loc}: ` : ''}${d.msg} (${d.type})`)
- }
+ for (const d of e.details ?? server?.details ?? []) lines.push(` - ${detailLine(d)}`)
const hint = resolveHint(e, opts)
if (hint !== undefined) lines.push(`${style.magenta('hint:')} ${style.cyan(hint)}`)
+ for (const h of server?.hints ?? []) lines.push(nextLine(h, style))
if (e.method !== undefined && e.url !== undefined) lines.push(`request: ${e.method} ${e.url}`)
if (e.http_status !== undefined) lines.push(`http_status: ${e.http_status}`)
if (opts.verbose && e.raw_response) lines.push(`raw_response: ${redactBearer(e.raw_response)}`)
diff --git a/cli/src/main.test.ts b/cli/src/main.test.ts
index ec38375e6a2..321dfdb1874 100644
--- a/cli/src/main.test.ts
+++ b/cli/src/main.test.ts
@@ -12,7 +12,7 @@ afterEach(async () => {
it('prints the envelope on stderr and returns the exit code', async () => {
w = await testContext({ login: false })
- const code = await main(['nope'], w.overrides)
+ const code = await main(['versoin'], w.overrides)
expect(code).toBe(2)
expect(JSON.parse(w.io.errBuf()).error.code).toBe('usage_invalid_flag')
expect(w.io.outBuf()).toBe('')
diff --git a/cli/src/plugins/catalog/index.test.ts b/cli/src/plugins/catalog/index.test.ts
index 00ddea739bb..7dca98e1c26 100644
--- a/cli/src/plugins/catalog/index.test.ts
+++ b/cli/src/plugins/catalog/index.test.ts
@@ -25,7 +25,6 @@ let dir: string
beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), 'difyctl-cat-'))
process.env.DIFY_CONFIG_DIR = dir
- process.env.DIFY_CACHE_DIR = dir
})
afterEach(() => {
delete process.env.DIFY_CONFIG_DIR
@@ -121,3 +120,22 @@ it('a cache it cannot write is an error naming the path', async () => {
})
expect(c.loaded).toBe(false)
})
+
+it('an unknown op id points at the help map, which lists every operation', async () => {
+ const c = await build()
+ await c.replace(FIXTURE)
+ expect(() => c.opOrThrow('get.nothing_here')).toThrow(
+ expect.objectContaining({ code: 'unknown_op', hint: 'run difyctl help' }),
+ )
+})
+
+it('keeps the cache in the config folder and says once that DIFY_CACHE_DIR is no longer used', async () => {
+ process.env.DIFY_CACHE_DIR = join(dir, 'old-cache')
+ const { streams, ctx } = await buildWithStreams()
+ const c = await ctx.get(catalog)
+ await ctx.get(catalog)
+ expect(c.path).toBe(join(dir, CATALOG_DIR_NAME, CACHE_FILE))
+ expect(streams.errBuf()).toBe(
+ 'DIFY_CACHE_DIR is no longer used; the catalog cache follows DIFY_CONFIG_DIR\n',
+ )
+})
diff --git a/cli/src/plugins/catalog/index.ts b/cli/src/plugins/catalog/index.ts
index ed59776757a..f9d0bb8246b 100644
--- a/cli/src/plugins/catalog/index.ts
+++ b/cli/src/plugins/catalog/index.ts
@@ -6,19 +6,19 @@ import { BaseError, notLoggedIn } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { errorMessage } from '@/errors/message'
import { definePlugin } from '@/kernel/plugin'
-import { env } from '@/plugins/env'
+import { helpHint } from '@/plugins/commands/command'
+import { ENV, env } from '@/plugins/env'
import { io } from '@/plugins/io'
import { session } from '@/plugins/session'
+import { DIR_PERM, FILE_PERM } from '@/store/dir'
import { pid, resolvePlatform } from '@/sys'
import { bareHost } from '@/util/host'
-import { BINARY } from '@/version/info'
import { parseCatalog } from './types'
export const CATALOG_DIR_NAME = 'catalog'
const HOST_SEPARATOR_REPLACEMENT = '_'
-const FILE_MODE = 0o600
-const DIR_MODE = 0o700
const UNREADABLE_CACHE_PREFIX = 'ignoring unreadable catalog cache '
+const CACHE_DIR_RETIRED = `${ENV.CacheDir} is no longer used; the catalog cache follows ${ENV.ConfigDir}`
const ENOENT = 'ENOENT'
export type { CatalogDoc, CatalogOp, Example, JsonSchema } from './types'
@@ -39,9 +39,9 @@ export function fingerprintOf(bytes: Uint8Array): string {
return createHash('sha256').update(bytes).digest('hex')
}
-function cachePath(cacheDir: string, server: string): string {
+function cachePath(configDir: string, server: string): string {
const key = bareHost(server).split(':').join(HOST_SEPARATOR_REPLACEMENT)
- return join(cacheDir, CATALOG_DIR_NAME, `${key}.json`)
+ return join(configDir, CATALOG_DIR_NAME, `${key}.json`)
}
function isMissingFile(err: unknown): boolean {
@@ -53,8 +53,8 @@ function isMissingFile(err: unknown): boolean {
async function writeAtomically(path: string, bytes: Uint8Array): Promise<void> {
const tmp = `${path}.tmp.${pid()}.${Date.now()}`
try {
- await fsp.mkdir(dirname(path), { recursive: true, mode: DIR_MODE })
- await fsp.writeFile(tmp, bytes, { mode: FILE_MODE })
+ await fsp.mkdir(dirname(path), { recursive: true, mode: DIR_PERM })
+ await fsp.writeFile(tmp, bytes, { mode: FILE_PERM })
resolvePlatform().atomicReplace(tmp, path)
} catch (cause) {
try {
@@ -74,10 +74,11 @@ export const catalog = definePlugin({
name: 'catalog',
needs: [env, session, io],
build: async (ctx): Promise<CatalogService> => {
- const { cacheDir } = await ctx.get(env)
+ const { configDir, cacheDirSet } = await ctx.get(env)
+ if (cacheDirSet) (await ctx.get(io)).notice(CACHE_DIR_RETIRED)
const sessionService = await ctx.get(session)
const login = await sessionService.current()
- const path = login === null ? undefined : cachePath(cacheDir, login.server)
+ const path = login === null ? undefined : cachePath(configDir, login.server)
let bytes: Uint8Array | undefined
let doc: CatalogDoc | undefined
@@ -116,7 +117,7 @@ export const catalog = definePlugin({
throw new BaseError({
code: ErrorCode.UnknownOp,
message: `unknown op "${id}"`,
- hint: `run ${BINARY} ops`,
+ hint: helpHint(),
})
},
ops: () => doc?.ops ?? {},
diff --git a/cli/src/plugins/commands/command.ts b/cli/src/plugins/commands/command.ts
index b590fde155d..64deb027bc5 100644
--- a/cli/src/plugins/commands/command.ts
+++ b/cli/src/plugins/commands/command.ts
@@ -5,10 +5,11 @@ import type { Example, JsonSchema } from '@/plugins/catalog'
import type { Printable } from '@/sys/io/view'
import { z } from 'zod'
import { validateInput } from '@/call/validate'
-import { BaseError } from '@/errors/base'
+import { BaseError, LOC_SEPARATOR } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { inputSchema } from '@/plugins/argv/parse'
import { COMMAND_SEPARATOR } from '@/protocol/op-id'
+import { typedName } from '@/util/flag-name'
import { BINARY } from '@/version/info'
import { commandRow } from './describe'
@@ -23,6 +24,34 @@ export function helpHint(...words: readonly string[]): string {
return ['run', BINARY, HELP_WORD, ...words].join(COMMAND_SEPARATOR)
}
+type InputCheck = Readonly<{
+ command: readonly string[]
+ schema: JsonSchema
+ positional?: readonly string[]
+ input: Record<string, unknown>
+}>
+
+function typedField(loc: readonly (string | number)[], positional: readonly string[] = []) {
+ const [head, ...rest] = loc
+ if (typeof head !== 'string') return undefined
+ return [typedName(head, positional), ...rest].join(LOC_SEPARATOR)
+}
+
+export function assertValidInput(check: InputCheck): void {
+ const details = validateInput(check.schema, check.input)
+ if (details.length === 0) return
+ throw new BaseError({
+ code: ErrorCode.InputInvalid,
+ message: `invalid input for "${check.command.join(COMMAND_SEPARATOR)}"`,
+ hint: helpHint(...check.command),
+ details: details.map((detail) => ({
+ ...detail,
+ field: typedField(detail.loc, check.positional),
+ })),
+ schema: check.schema,
+ })
+}
+
/** Returned by a command that already wrote its output or needs a non-zero exit. */
export class Outcome {
readonly code: ExitCodeValue
@@ -69,17 +98,7 @@ export abstract class Command<S extends z.ZodObject = z.ZodObject> {
input: Record<string, unknown>,
path: readonly string[],
): Record<string, unknown> {
- const schema = this.schema()
- const details = validateInput(schema, input)
- if (details.length > 0) {
- throw new BaseError({
- code: ErrorCode.InputInvalid,
- message: `invalid input for "${path.join(COMMAND_SEPARATOR)}"`,
- hint: helpHint(...path),
- details: [...details],
- schema,
- })
- }
+ assertValidInput({ command: path, schema: this.schema(), positional: this.positional, input })
const parsed = this.input.safeParse(input)
if (!parsed.success) {
throw new BaseError({
diff --git a/cli/src/plugins/commands/describe.test.ts b/cli/src/plugins/commands/describe.test.ts
index 1a8b392606b..1e052ea43ce 100644
--- a/cli/src/plugins/commands/describe.test.ts
+++ b/cli/src/plugins/commands/describe.test.ts
@@ -24,7 +24,7 @@ it('renders the row from the statics with a JSON Schema input', () => {
summary: 'Do a thing',
effect: 'write',
positional: ['id'],
- examples: [{ title: 'Basic', input: { id: 'x' } }],
+ examples: [{ title: 'Basic', input: { id: 'x' }, command: 'difyctl fake thing x' }],
})
expect(row.input).toMatchObject({
type: 'object',
diff --git a/cli/src/plugins/commands/describe.ts b/cli/src/plugins/commands/describe.ts
index f274878e30d..6f861c1e1f7 100644
--- a/cli/src/plugins/commands/describe.ts
+++ b/cli/src/plugins/commands/describe.ts
@@ -1,6 +1,9 @@
import type { CommandConstructor, CommandEffect } from './command'
-import type { Example, JsonSchema } from '@/plugins/catalog'
+import type { CommandExample } from './examples'
+import type { JsonSchema } from '@/plugins/catalog'
+import { argToken } from '@/util/flag-name'
import { BINARY } from '@/version/info'
+import { commandExamples } from './examples'
export type CommandRow = {
id: string
@@ -9,7 +12,7 @@ export type CommandRow = {
effect?: CommandEffect
input: JsonSchema
positional: readonly string[]
- examples: readonly Example[]
+ examples: readonly CommandExample[]
}
// The op side of a descriptor: present once a command wraps a catalog op instead of a
@@ -31,14 +34,15 @@ const FLAGS = '[flags]'
export function commandRow(ctor: CommandConstructor, path: readonly string[]): CommandRow {
const id = path.join(' ')
- const args = ctor.positional.map((name) => `<${name}>`)
+ const args = ctor.positional.map(argToken)
+ const input = ctor.schema()
const row: CommandRow = {
id,
usage: [BINARY, id, ...args, FLAGS].join(' '),
summary: ctor.summary,
- input: ctor.schema(),
+ input,
positional: ctor.positional,
- examples: ctor.examples,
+ examples: commandExamples({ id, input, positional: ctor.positional }, ctor.examples),
}
return ctor.effect === undefined ? row : { ...row, effect: ctor.effect }
}
diff --git a/cli/src/plugins/commands/examples.ts b/cli/src/plugins/commands/examples.ts
new file mode 100644
index 00000000000..1c60bfa1188
--- /dev/null
+++ b/cli/src/plugins/commands/examples.ts
@@ -0,0 +1,65 @@
+import type { Example, JsonSchema } from '@/plugins/catalog'
+import { COMMAND_SEPARATOR } from '@/protocol/op-id'
+import { isRepeatable, isScalar, propertiesOf, shapeOf } from '@/protocol/shape'
+import { argToken, flagToken } from '@/util/flag-name'
+import { shellWord } from '@/util/shell-word'
+import { BINARY } from '@/version/info'
+
+export type CommandExample = Example & Readonly<{ command: string }>
+
+type ExampleSource = Readonly<{ id: string; input: JsonSchema; positional: readonly string[] }>
+
+const PLACEHOLDER = /^<[^<>]*>$/
+const SKELETON_TITLE = 'Required fields'
+
+// A placeholder stands for a value the caller fills in, whatever the field's shape.
+function word(text: string): string {
+ return PLACEHOLDER.test(text) ? text : shellWord(text)
+}
+
+function valueToken(property: JsonSchema | undefined, value: unknown): string {
+ const scalar =
+ typeof value === 'string' || (property !== undefined && isScalar(shapeOf(property)))
+ return word(scalar ? String(value) : JSON.stringify(value))
+}
+
+// How the field is typed: a boolean as its presence, a repeatable list as the flag
+// once per item, anything else as one value.
+function flagTokens(name: string, property: JsonSchema | undefined, value: unknown): string[] {
+ const flag = flagToken(name)
+ if (value === true) return [flag]
+ if (value === false) return [`${flag}=false`]
+ if (property !== undefined && isRepeatable(shapeOf(property)) && Array.isArray(value))
+ return value.flatMap((item) => [flag, word(String(item))])
+ return [flag, valueToken(property, value)]
+}
+
+// Positionals keep their declared order, so an example that skips one does not shift the
+// rest along: the one it skipped prints as itself.
+export function exampleLine(d: ExampleSource, example: Example): string {
+ const properties = propertiesOf(d.input)
+ const flags = Object.keys(example.input).filter((name) => !d.positional.includes(name))
+ return [
+ BINARY,
+ d.id,
+ ...d.positional.map((name) =>
+ name in example.input ? valueToken(properties[name], example.input[name]) : argToken(name),
+ ),
+ ...flags.flatMap((name) => flagTokens(name, properties[name], example.input[name])),
+ ].join(COMMAND_SEPARATOR)
+}
+
+export function commandExamples(d: ExampleSource, examples: readonly Example[]): CommandExample[] {
+ return examples.map((example) => ({ ...example, command: exampleLine(d, example) }))
+}
+
+// The text view of a command that ships no example still gets a runnable line: the
+// required fields, each standing for itself.
+export function skeletonExample(d: ExampleSource): CommandExample {
+ const required = Array.isArray(d.input.required) ? d.input.required.map(String) : []
+ const example = {
+ title: SKELETON_TITLE,
+ input: Object.fromEntries(required.map((name) => [name, argToken(name)])),
+ }
+ return { ...example, command: exampleLine(d, example) }
+}
diff --git a/cli/src/plugins/commands/help.test.ts b/cli/src/plugins/commands/help.test.ts
index fcac90ac680..9154a27515e 100644
--- a/cli/src/plugins/commands/help.test.ts
+++ b/cli/src/plugins/commands/help.test.ts
@@ -68,7 +68,7 @@ it('every command the tree hides comes back with includeHidden', () => {
})
it('search ranks the plain words against ids, summaries, fields and examples', () => {
- expect(helpSearch(['chatbot'], tree).entries[0]).toMatchObject({
+ expect(helpSearch(['chatbot', 'streams'], tree).entries[0]).toMatchObject({
id: 'run console_app chat',
kind: 'sse',
})
@@ -96,7 +96,7 @@ it('the pointer names help and the skill in both forms', () => {
expect(pointed.json).toEqual({
message: 'difyctl has no built-in business commands; every server operation is a command',
help: 'difyctl help',
- skill: 'difyctl install skills <dir>',
+ skill: 'difyctl install skills <skills root>',
})
expect(pointed.text(plain).split('\n')).toEqual(Object.values(pointed.json))
})
diff --git a/cli/src/plugins/commands/help.ts b/cli/src/plugins/commands/help.ts
index cc82074f654..8026ed5e92c 100644
--- a/cli/src/plugins/commands/help.ts
+++ b/cli/src/plugins/commands/help.ts
@@ -4,7 +4,7 @@ import type { SearchDoc } from '@/discovery/search'
import type { View } from '@/sys/io/view'
import { search, searchDoc } from '@/discovery/search'
import { byHead, groupsOf, namespacesOf, under } from '@/discovery/tree'
-import { COMMAND_SEPARATOR, OP_SEPARATOR, spacedId } from '@/protocol/op-id'
+import { COMMAND_SEPARATOR, commandWords, OP_SEPARATOR } from '@/protocol/op-id'
import { view } from '@/sys/io/view'
import { BINARY } from '@/version/info'
import { HELP_WORD } from './command'
@@ -12,7 +12,7 @@ import { collectCommands } from './registry'
const SEARCH_LIMIT = 20
const NEWLINE = '\n'
-const SKILL_WORDS = 'install skills <dir>'
+const SKILL_COMMAND = [BINARY, 'install', 'skills', '<skills root>'].join(COMMAND_SEPARATOR)
const POINTER_MESSAGE = `${BINARY} has no built-in business commands; every server operation is a command`
export type HelpEntry = {
@@ -32,7 +32,7 @@ export function pointer(): View<Record<string, string>> {
const json = {
message: POINTER_MESSAGE,
help: [BINARY, HELP_WORD].join(COMMAND_SEPARATOR),
- skill: [BINARY, SKILL_WORDS].join(COMMAND_SEPARATOR),
+ skill: SKILL_COMMAND,
}
return view(json, () => Object.values(json).join(NEWLINE))
}
@@ -41,7 +41,7 @@ export function pointer(): View<Record<string, string>> {
export function spacedWords(words: readonly string[]): readonly string[] {
const [only] = words
if (words.length !== 1 || only === undefined || !only.includes(OP_SEPARATOR)) return words
- return spacedId(only).split(COMMAND_SEPARATOR)
+ return commandWords(only)
}
function entryOf(ctor: CommandConstructor, id: string): HelpEntry {
diff --git a/cli/src/plugins/commands/index.test.ts b/cli/src/plugins/commands/index.test.ts
index e1fec9546b2..b5296214d03 100644
--- a/cli/src/plugins/commands/index.test.ts
+++ b/cli/src/plugins/commands/index.test.ts
@@ -1,10 +1,12 @@
import type { TestWorld } from '@test/fixtures/kernel'
+import type { BaseError } from '@/errors/base'
import type { CommandTree } from '@/plugins/commands/registry'
import { readFileSync } from 'node:fs'
import { join } from 'node:path'
import { testContext } from '@test/fixtures/kernel'
import { afterEach, expect, it } from 'vite-plus/test'
import { z } from 'zod'
+import { ExitCode } from '@/errors/codes'
import { parseCatalog } from '@/plugins/catalog'
import { Command } from '@/plugins/commands/command'
import { propertiesOf } from '@/protocol/shape'
@@ -31,7 +33,7 @@ it('bare difyctl prints a pointer to help and the skill, and makes no request',
expect(JSON.parse(w.io.outBuf())).toEqual({
message: 'difyctl has no built-in business commands; every server operation is a command',
help: 'difyctl help',
- skill: 'difyctl install skills <dir>',
+ skill: 'difyctl install skills <skills root>',
})
expect(w.mock.requestCount).toBe(0)
})
@@ -67,7 +69,7 @@ it('the map with no server known is the static half and says so on stderr', asyn
const map = JSON.parse(w.io.outBuf())
expect(map.version).toMatchObject({ count: 1 })
expect(map.console_app).toBeUndefined()
- expect(w.io.errBuf()).toMatch(/log in to list server operations/)
+ expect(w.io.errBuf()).toMatch(/not logged in: run difyctl help login/)
expect(w.mock.requestCount).toBe(0)
})
@@ -78,8 +80,9 @@ it('the map still prints the static half when the catalog cannot be fetched', as
const map = JSON.parse(w.io.outBuf())
expect(map.version).toMatchObject({ count: 1 })
expect(map.console_app).toBeUndefined()
- expect(w.io.errBuf().trim().split('\n')).toHaveLength(1)
- expect(w.io.errBuf()).toMatch(/^could not list server operations: failed to fetch the catalog: /)
+ const [couldNotList, ...rest] = w.io.errBuf().trim().split('\n')
+ expect(couldNotList).toMatch(/^could not list server operations: failed to fetch the catalog: /)
+ expect(rest).toEqual([])
})
it('help accepts a dotted id and prints the same descriptor as the spaced path', async () => {
@@ -145,11 +148,10 @@ it('help routes a word to a namespace listing or a search, and --full is the fla
const c = await world(true, ['help', 'get'])
await (await c.ctx.get(commands)).run()
const ids = JSON.parse(c.io.outBuf()).entries.map((e: { id: string }) => e.id)
- expect(ids).toContain('get skills')
expect(ids).toContain('get workspace member')
expect(ids).toEqual([...ids].sort())
- const d = await world(true, ['help', 'chatbot'])
+ const d = await world(true, ['help', 'chatbot', 'streams'])
await (await d.ctx.get(commands)).run()
expect(JSON.parse(d.io.outBuf()).entries[0]).toMatchObject({
id: 'run console_app chat',
@@ -218,7 +220,7 @@ it('takes --verbose anywhere and keeps it out of the command input', async () =>
const b = await world(false, ['--verbose', 'version'])
expect(await (await b.ctx.get(commands)).run()).toBe(0)
expect(JSON.parse(b.io.outBuf()).client.version).toBe('0.0.0-test')
- const c = await world(false, ['nope', '--verbose'])
+ const c = await world(false, ['versoin', '--verbose'])
await expect((await c.ctx.get(commands)).run()).rejects.toMatchObject({
code: 'usage_invalid_flag',
})
@@ -254,18 +256,29 @@ it('a command word may be spelled with dashes where the op id has underscores',
})
})
-it('an unknown path refetches the catalog once before giving up', async () => {
- const w = await world(true, ['get', 'nope'])
- await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({
- code: 'usage_invalid_flag',
- message: 'unknown command: get nope',
+it('an unknown path refetches the catalog once, then is unknown_op (exit 6)', async () => {
+ const w = await world(true, ['get', 'qqqq'])
+ const miss = (await w.ctx.get(commands)).run()
+ await expect(miss).rejects.toMatchObject({
+ code: 'unknown_op',
+ message: 'no command or server operation named get qqqq',
hint: 'run difyctl help',
})
+ await expect(miss).rejects.toSatisfy((err: BaseError) => err.exit() === ExitCode.Catalog)
expect(w.mock.requestCount).toBe(2) // the cached catalog, then one refetch
const typo = await world(true, ['get', 'consol_app'])
await expect((await typo.ctx.get(commands)).run()).rejects.toMatchObject({
- hint: 'did you mean: get console_app',
+ code: 'unknown_op',
+ hint: 'did you mean: get console_app, get console_app version',
+ })
+})
+
+it('a typo of a static command stays exit 2 once the catalog is loaded', async () => {
+ const w = await world(true, ['versoin'])
+ await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({
+ code: 'usage_invalid_flag',
+ hint: 'did you mean: version',
})
})
@@ -302,13 +315,33 @@ it('an unreachable catalog costs a notice, not the static suggestion', async ()
expect(w.io.errBuf()).toMatch(/^could not list server operations: failed to fetch the catalog: /)
})
-it('without a login only statics resolve and the hint says to log in', async () => {
+it('an unreachable catalog makes a word no static claims catalog_unavailable (exit 6)', async () => {
+ const w = await world(true, ['get', 'console_app'])
+ w.mock.setScenario('no-catalog')
+ const miss = (await w.ctx.get(commands)).run()
+ await expect(miss).rejects.toMatchObject({
+ code: 'catalog_unavailable',
+ message: expect.stringMatching(/^failed to fetch the catalog: /),
+ hint: expect.any(String),
+ })
+ await expect(miss).rejects.toSatisfy((err: BaseError) => err.exit() === ExitCode.Catalog)
+})
+
+it('without a login a word no static claims is not_logged_in (exit 4)', async () => {
const w = await world(false, ['get', 'console_app'])
- await expect((await w.ctx.get(commands)).run()).rejects.toMatchObject({
- code: 'usage_invalid_flag',
- message: 'unknown command: get console_app',
- hint: 'log in to use server operations',
+ const miss = (await w.ctx.get(commands)).run()
+ await expect(miss).rejects.toMatchObject({
+ code: 'not_logged_in',
+ message: 'not logged in: get console_app may be a server operation; log in to load them',
+ hint: 'run difyctl help login',
})
+ await expect(miss).rejects.toSatisfy((err: BaseError) => err.exit() === ExitCode.Auth)
+ expect(w.mock.requestCount).toBe(0)
+})
+
+it('without a login a namespace still lists its static commands', async () => {
+ const w = await world(false, ['get'])
+ expect(await (await w.ctx.get(commands)).run()).toBe(0)
expect(w.mock.requestCount).toBe(0)
})
diff --git a/cli/src/plugins/commands/index.ts b/cli/src/plugins/commands/index.ts
index f6abcbf5431..be1109107a7 100644
--- a/cli/src/plugins/commands/index.ts
+++ b/cli/src/plugins/commands/index.ts
@@ -4,7 +4,7 @@ import type { CollectOptions, CommandTree, ResolvedCommand } from '@/plugins/com
import type { IOService } from '@/plugins/io'
import type { OpsService, TreeOptions } from '@/plugins/ops'
import { commandTree } from '@/commands/tree'
-import { BaseError } from '@/errors/base'
+import { BaseError, isBaseError, notLoggedInMessage } from '@/errors/base'
import { ErrorCode, ExitCode } from '@/errors/codes'
import { errorMessage } from '@/errors/message'
import { definePlugin } from '@/kernel/plugin'
@@ -41,8 +41,8 @@ const HELP_FLAGS: readonly string[] = ['--help', '-h']
const FULL_FLAG = '--full'
const ALL_FLAG = '--all'
const FLAG_PREFIX = '-'
-const NO_SERVER_NOTICE = 'log in to list server operations'
-const NO_SERVER_HINT = 'log in to use server operations'
+const NO_SERVER_NOTICE = notLoggedInMessage(helpHint('login'))
+const MAYBE_AN_OP = 'may be a server operation; log in to load them'
const OPS_UNAVAILABLE_PREFIX = 'could not list server operations: '
const NO_MATCH_NOTICE = `nothing matched; ${helpHint()} for the map`
const NO_REST: readonly string[] = []
@@ -77,41 +77,92 @@ function leadingWords(tokens: readonly string[]): number {
return at === -1 ? tokens.length : at
}
+/** What a catalog load gave: the value, or why there is none (`failure` unset when logged out). */
+type Fetched<T> = Readonly<{ value: T }> | Readonly<{ value?: undefined; failure?: unknown }>
+
// An unreachable server must not cost the caller the static half of help.
async function fromOps<T>(
ctx: CommandContext,
streams: IOService,
load: (service: OpsService) => Promise<T>,
-): Promise<T | undefined> {
+): Promise<Fetched<T>> {
const login = await (await ctx.get(session)).current()
if (login === null) {
streams.notice(NO_SERVER_NOTICE)
- return undefined
+ return {}
}
try {
- return await load(await ctx.get(ops))
- } catch (err) {
- streams.notice(`${OPS_UNAVAILABLE_PREFIX}${errorMessage(err)}`)
- return undefined
+ return { value: await load(await ctx.get(ops)) }
+ } catch (failure) {
+ streams.notice(`${OPS_UNAVAILABLE_PREFIX}${errorMessage(failure)}`)
+ return { failure }
}
}
-function unknownCommand(tree: CommandTree, words: readonly string[], fallback: string): BaseError {
+function suggestionHint(tree: CommandTree, words: readonly string[]): string | undefined {
const suggestions = findSuggestions(tree, [...words])
+ return suggestions.length > 0 ? `did you mean: ${suggestions.join(', ')}` : undefined
+}
+
+function unknownCommand(words: readonly string[], hint: string): BaseError {
return new BaseError({
code: ErrorCode.UsageInvalidFlag,
message: `unknown command: ${words.join(COMMAND_SEPARATOR)}`,
- hint: suggestions.length > 0 ? `did you mean: ${suggestions.join(', ')}` : fallback,
+ hint,
})
}
+/** The error for words no command claimed, given the widest tree resolution got. */
+type Miss = (tree: CommandTree, words: readonly string[]) => BaseError
+
+const unresolved: Miss = (tree, words) =>
+ unknownCommand(words, suggestionHint(tree, words) ?? helpHint())
+
+// A near miss of a static command is a typo (exit 2) whether or not ops could load.
+function unlessStaticTypo(statics: CommandTree, miss: Miss): Miss {
+ return (tree, words) => {
+ const typo = suggestionHint(statics, words)
+ return typo === undefined ? miss(tree, words) : unknownCommand(words, typo)
+ }
+}
+
+const loggedOut: Miss = (_tree, words) =>
+ new BaseError({
+ code: ErrorCode.NotLoggedIn,
+ message: notLoggedInMessage(`${words.join(COMMAND_SEPARATOR)} ${MAYBE_AN_OP}`),
+ hint: helpHint('login'),
+ })
+
+const unknownOp: Miss = (tree, words) =>
+ new BaseError({
+ code: ErrorCode.UnknownOp,
+ message: `no command or server operation named ${words.join(COMMAND_SEPARATOR)}`,
+ hint: suggestionHint(tree, words) ?? helpHint(),
+ })
+
+function catalogUnavailable(failure: unknown): BaseError {
+ return isBaseError(failure)
+ ? failure
+ : new BaseError({
+ code: ErrorCode.CatalogUnavailable,
+ message: `${OPS_UNAVAILABLE_PREFIX}${errorMessage(failure)}`,
+ cause: failure,
+ })
+}
+
+// Words that might name an op cannot be called unknown when the ops never loaded.
+function unloaded(statics: CommandTree, fetched: Fetched<unknown>): Miss | undefined {
+ if (!('failure' in fetched)) return undefined
+ return unlessStaticTypo(statics, () => catalogUnavailable(fetched.failure))
+}
+
type Discovery = Readonly<{
tree: CommandTree
path: readonly string[]
full: boolean
listing: CollectOptions
wantsHelp: boolean
- missHint?: string
+ miss: Miss
ctx: CommandContext
streams: IOService
}>
@@ -140,7 +191,7 @@ async function discover(args: Discovery): Promise<number> {
await streams.document(listingView(under))
return ExitCode.Success
}
- if (!args.wantsHelp) throw unknownCommand(tree, path, args.missHint ?? helpHint())
+ if (!args.wantsHelp) throw args.miss(tree, path)
const found = helpSearch(path, tree, listing)
if (found.total === 0) streams.notice(NO_MATCH_NOTICE)
@@ -151,8 +202,8 @@ async function discover(args: Discovery): Promise<number> {
type Resolution = {
readonly resolved: ResolvedCommand | undefined
readonly tree: CommandTree
- /** Set only when a miss has a better explanation than the generic help hint. */
- readonly missHint?: string
+ /** Set only when a miss has a better explanation than an unknown command. */
+ readonly miss?: Miss
}
type Walk = Readonly<{
@@ -172,30 +223,36 @@ function answerable(walk: Walk, cached: CommandTree): boolean {
// Statics resolve without touching the catalog. A miss walks the server's ops as
// commands too: the cached catalog first, then one refetch in case the op is newer
-// than the cache. A server that cannot answer costs the caller nothing but a notice —
+// than the cache. A server that cannot answer costs help nothing but a notice —
// resolution falls back to the widest tree it did get, which is also the tree help
-// lists, so the catalog is loaded at most once per run.
+// lists, so the catalog is loaded at most once per run. A plain miss then reports the
+// failed load rather than an unknown command.
async function resolveWithOps(walk: Walk): Promise<Resolution> {
const { ctx, streams, tree } = walk
const path = [...walk.path]
const direct = resolveCommand(tree, path)
if (direct !== undefined) return { resolved: direct, tree }
- // A help view explains a missing catalog on stderr; a plain miss gets the hint instead.
+ // A help view explains a missing catalog on stderr; a plain miss says to log in.
if (!walk.wantsHelp && (await (await ctx.get(session)).current()) === null)
- return { resolved: undefined, tree, missHint: NO_SERVER_HINT }
+ return { resolved: undefined, tree, miss: unlessStaticTypo(tree, loggedOut) }
const known = await fromOps(ctx, streams, (service) => service.commands(EVERY_OP))
- if (known === undefined) return { resolved: undefined, tree }
- const cached = mergeTrees(tree, known).tree
+ if (known.value === undefined) return { resolved: undefined, tree, miss: unloaded(tree, known) }
+ const cached = mergeTrees(tree, known.value).tree
const fromCache = resolveCommand(cached, path)
if (fromCache !== undefined || answerable(walk, cached))
return { resolved: fromCache, tree: cached }
const refetched = await fromOps(ctx, streams, (service) => service.commands(EVERY_OP_FRESH))
- if (refetched === undefined) return { resolved: undefined, tree: cached }
- const fresh = mergeTrees(tree, refetched).tree
- return { resolved: resolveCommand(fresh, path), tree: fresh }
+ if (refetched.value === undefined)
+ return { resolved: undefined, tree: cached, miss: unloaded(tree, refetched) }
+ const fresh = mergeTrees(tree, refetched.value).tree
+ return {
+ resolved: resolveCommand(fresh, path),
+ tree: fresh,
+ miss: unlessStaticTypo(tree, unknownOp),
+ }
}
export async function runPipeline(tree: CommandTree, ctx: CommandContext): Promise<number> {
@@ -225,7 +282,7 @@ export async function runPipeline(tree: CommandTree, ctx: CommandContext): Promi
full: argv.includes(FULL_FLAG),
listing: { includeHidden: argv.includes(ALL_FLAG) },
wantsHelp,
- missHint: walked.missHint,
+ miss: walked.miss ?? unresolved,
ctx,
streams,
})
diff --git a/cli/src/plugins/commands/text.test.ts b/cli/src/plugins/commands/text.test.ts
index fb4567a6248..a6abdb70d21 100644
--- a/cli/src/plugins/commands/text.test.ts
+++ b/cli/src/plugins/commands/text.test.ts
@@ -7,8 +7,9 @@ import SkillsInstall from '@/commands/install/skills/index'
import { parseCatalog } from '@/plugins/catalog'
import { colorScheme } from '@/sys/io/color'
import { commandRow } from './describe'
+import { commandExamples, exampleLine } from './examples'
import { helpMap } from './help'
-import { descriptorView, exampleLine, fieldRows, listingView, mapView, SECTIONS } from './text'
+import { descriptorView, fieldRows, listingView, mapView, SECTIONS } from './text'
const OPS = parseCatalog(readFileSync(join(__dirname, '../../../test/fixtures/catalog.json'))).ops
const plain = colorScheme(false)
@@ -23,7 +24,7 @@ function opDescriptor(id: string, path: readonly string[]): Descriptor {
effect: 'write',
input: op.input,
positional: [],
- examples: op.examples,
+ examples: commandExamples({ id: path.join(' '), input: op.input, positional: [] }, op.examples),
op: id,
method: op.method,
path: op.path,
@@ -59,18 +60,18 @@ it('renders an op descriptor with input, options, global and examples', () => {
difyctl run console_app workflow [flags]
Flags
- --app-id string required
- --attachments file[] optional Local files attached to the run itself (the app's
- \`sys.files\`), not to a variable
- --files map<string, json> optional Local files keyed by the app's file variable name; the
- server uploads each one and sets \`inputs[<name>]\`. Send a
- list (part name \`files[<name>][]\`) for a file-list variable
- --inputs map<string, json> required Variables declared by the app. The exact shape is per app:
- read \`input_schema\` from describe.console_app. A file
- variable takes a Dify file mapping (remote url or upload id)
- here, or a local file in \`files\`, not both.
- --workflow-id string optional Pin a published workflow version
- --workspace-id string optional Workspace that owns the app
+ --app-id string required
+ --attachments file[] optional Local files attached to the run itself (the app's
+ \`sys.files\`), not to a variable
+ --files map<string, file | file[]> optional Local files keyed by the app's file variable name; the
+ server uploads each one and sets \`inputs[<name>]\`. Send a
+ list (part name \`files[<name>][]\`) for a file-list variable
+ --inputs map<string, json> required Variables declared by the app. The exact shape is per app:
+ read \`input_schema\` from describe.console_app. A file
+ variable takes a Dify file mapping (remote url or upload id)
+ here, or a local file in \`files\`, not both.
+ --workflow-id string optional Pin a published workflow version
+ --workspace-id string optional Workspace that owns the app
Options
--input string optional Operation input as JSON, @file or @- for stdin
@@ -92,7 +93,7 @@ it('renders an op descriptor with input, options, global and examples', () => {
it('renders a static descriptor with arguments and flags', () => {
expect(descriptorView(skillsInstall).text(plain)).toMatchInlineSnapshot(`
- "install skills Write skills from the collection into a skills root write
+ "install skills Write the difyctl skill into a skills root write
Usage
difyctl install skills <dir> [flags]
@@ -102,19 +103,16 @@ it('renders a static descriptor with arguments and flags', () => {
per skill
Flags
- --skill string[] [] Skill to install (repeatable); default: the whole collection
- --from string "https://github.com/langgenius/dify/tree/0000000/skills" Where the skills come from: a GitHub folder URL or a local
- folder
+ --from string optional A local skill folder to install instead of the one built
+ into difyctl
Global
--verbose boolean false Keep the raw server response in error envelopes
--json boolean false Print JSON even on a terminal
Examples
- # Install every skill for Claude Code
- difyctl install skills ~/.claude/skills
- # Install one skill for Codex
- difyctl install skills ~/.codex/skills --skill difyctl"
+ # Install the skill for Claude Code
+ difyctl install skills ~/.claude/skills"
`)
})
@@ -125,9 +123,9 @@ it('example lines put positionals first, scalars as --flag value, non-scalars as
expect(
exampleLine(skillsInstall, {
title: 't',
- input: { dir: '~/.claude/skills', skill: ['difyctl'] },
+ input: { dir: '~/.claude/skills', from: './skill' },
}),
- ).toBe('difyctl install skills ~/.claude/skills --skill difyctl')
+ ).toBe('difyctl install skills ~/.claude/skills --from ./skill')
})
it('a missing positional prints as itself and a non-scalar one as json', () => {
@@ -205,10 +203,9 @@ it('a description prints its first line only', () => {
})
it('an op without examples prints a skeleton of its required fields', () => {
+ const skeleton = 'difyctl run console_app workflow --app-id <app_id> --inputs <inputs>'
expect(workflowRun.examples).toEqual([])
- expect(descriptorView(workflowRun).text(plain)).toContain(
- 'difyctl run console_app workflow --app-id <app_id> --inputs <inputs>',
- )
+ expect(descriptorView(workflowRun).text(plain)).toContain(skeleton)
})
it('the map names each head, leaves by summary and groups by count', () => {
diff --git a/cli/src/plugins/commands/text.ts b/cli/src/plugins/commands/text.ts
index e60b44dee45..0e25c2d2f02 100644
--- a/cli/src/plugins/commands/text.ts
+++ b/cli/src/plugins/commands/text.ts
@@ -1,16 +1,16 @@
import type { CommandEffect } from './command'
import type { Descriptor } from './describe'
import type { HelpEntry, HelpHead, HelpListing, HelpMap } from './help'
-import type { Example, JsonSchema } from '@/plugins/catalog'
+import type { JsonSchema } from '@/plugins/catalog'
import type { ColorScheme } from '@/sys/io/color'
import type { View } from '@/sys/io/view'
import { inputSchema } from '@/plugins/argv/parse'
import { GLOBAL_INPUT } from '@/plugins/global-flags'
import { COMMAND_SEPARATOR } from '@/protocol/op-id'
-import { isRepeatable, isScalar, labelOf, propertiesOf, shapeOf } from '@/protocol/shape'
+import { labelOf, propertiesOf, shapeOf } from '@/protocol/shape'
import { view } from '@/sys/io/view'
-import { flagFor } from '@/util/flag-name'
-import { BINARY } from '@/version/info'
+import { argToken, flagToken } from '@/util/flag-name'
+import { skeletonExample } from './examples'
export type FieldRow = Readonly<{
name: string
@@ -25,7 +25,6 @@ type Tagged = Readonly<{ effect?: CommandEffect; kind?: string; deprecated?: boo
const PRESENCE = { Required: 'required', Optional: 'optional' } as const
const FIRST_LINE = /\r?\n/
-const PLACEHOLDER = /^<[^<>]*>$/
const GAP = ' '
const MAX_COLUMN_WIDTH = 60
const WORD_SEPARATOR = ' '
@@ -37,7 +36,6 @@ const LIST_SEPARATOR = ', '
const COMMAND_NOUN = { one: 'command', many: 'commands' } as const
const DEPRECATED = 'deprecated'
const NO_PIN = '(none)'
-const SKELETON_TITLE = 'Required fields'
const COMMENT = '#'
const NO_POSITIONAL: readonly string[] = []
@@ -100,7 +98,7 @@ export function fieldRows(schema: JsonSchema, positional: readonly string[]): Fi
function rowsToLines(rows: readonly FieldRow[]): string[] {
return aligned(
rows.map((row) => [
- row.positional ? `<${row.name}>` : `--${flagFor(row.name)}`,
+ row.positional ? argToken(row.name) : flagToken(row.name),
row.label,
row.presence,
row.description,
@@ -108,47 +106,6 @@ function rowsToLines(rows: readonly FieldRow[]): string[] {
)
}
-// A placeholder stands for a value the caller fills in, whatever the field's shape.
-function valueToken(property: JsonSchema | undefined, value: unknown): string {
- const placeholder = typeof value === 'string' && PLACEHOLDER.test(value)
- const scalar = property !== undefined && isScalar(shapeOf(property))
- return placeholder || scalar ? String(value) : `'${JSON.stringify(value)}'`
-}
-
-// How the field is typed: a boolean as its presence, a repeatable list as the flag
-// once per item, anything else as one value.
-function flagTokens(name: string, property: JsonSchema | undefined, value: unknown): string[] {
- const flag = `--${flagFor(name)}`
- if (value === true) return [flag]
- if (value === false) return [`${flag}=false`]
- if (property !== undefined && isRepeatable(shapeOf(property)) && Array.isArray(value))
- return value.flatMap((item) => [flag, String(item)])
- return [flag, valueToken(property, value)]
-}
-
-// Positionals keep their declared order, so an example that skips one does not shift the
-// rest along: the one it skipped prints as itself.
-export function exampleLine(d: Descriptor, example: Example): string {
- const properties = propertiesOf(d.input)
- const flags = Object.keys(example.input).filter((name) => !d.positional.includes(name))
- return [
- BINARY,
- d.id,
- ...d.positional.map((name) =>
- name in example.input ? valueToken(properties[name], example.input[name]) : `<${name}>`,
- ),
- ...flags.flatMap((name) => flagTokens(name, properties[name], example.input[name])),
- ].join(COMMAND_SEPARATOR)
-}
-
-// A server that ships no example still gets a runnable line: the required fields,
-// each standing for itself.
-function examplesOf(d: Descriptor): readonly Example[] {
- if (d.examples.length > 0) return d.examples
- const required = Array.isArray(d.input.required) ? d.input.required.map(String) : []
- return [{ title: SKELETON_TITLE, input: Object.fromEntries(required.map((n) => [n, `<${n}>`])) }]
-}
-
export const SECTIONS: readonly Section[] = [
{ title: 'Usage', lines: (d) => [d.usage] },
{
@@ -170,9 +127,9 @@ export const SECTIONS: readonly Section[] = [
{
title: 'Examples',
lines: (d, style) =>
- examplesOf(d).flatMap((example) => [
+ (d.examples.length > 0 ? d.examples : [skeletonExample(d)]).flatMap((example) => [
style.dim(`${COMMENT} ${example.title}`),
- exampleLine(d, example),
+ example.command,
]),
},
{
diff --git a/cli/src/plugins/config/index.test.ts b/cli/src/plugins/config/index.test.ts
index 216aa9b55fe..31f84cfdc22 100644
--- a/cli/src/plugins/config/index.test.ts
+++ b/cli/src/plugins/config/index.test.ts
@@ -1,46 +1,84 @@
-import { mkdtempSync, writeFileSync } from 'node:fs'
+import type { BufferStreams } from '@/sys/io/streams'
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, expect, it } from 'vite-plus/test'
import { Context } from '@/kernel/context'
-import { config } from './index'
+import { io, ioService } from '@/plugins/io'
+import { bufferStreams } from '@/sys/io/streams'
+import { config, CONFIG_FILE_NAME } from './index'
let dir: string
+let file: string
+let streams: BufferStreams
beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), 'difyctl-cfg-'))
+ file = join(dir, CONFIG_FILE_NAME)
process.env.DIFY_CONFIG_DIR = dir
+ streams = bufferStreams()
})
afterEach(() => {
delete process.env.DIFY_CONFIG_DIR
})
+const load = () => new Context([[io, ioService(streams)]]).get(config)
+
it('returns defaults and the file path when nothing is on disk', async () => {
- const c = await new Context().get(config)
- expect(await c.get()).toEqual({
- schema_version: 1,
- http: { timeout: 30_000 },
- path: join(dir, 'config.yml'),
- })
+ const c = await load()
+ expect(await c.get()).toEqual({ http: { timeout: 30_000 }, path: file })
})
it('set / get / unset round-trip through yaml', async () => {
- const c = await new Context().get(config)
+ const c = await load()
await c.set('http.timeout', '5000')
expect(await c.get('http.timeout')).toBe(5000)
await c.unset('http.timeout')
expect(await c.get('http.timeout')).toBe(30_000)
})
-it('rejects unknown keys and wrong types with exit 2', async () => {
- const c = await new Context().get(config)
+it('rejects unknown keys and wrong types with exit 2, naming the file', async () => {
+ const c = await load()
await expect(c.set('nope', '1')).rejects.toMatchObject({ code: 'config_invalid_key' })
await expect(c.set('http.timeout', 'fast')).rejects.toMatchObject({
code: 'config_invalid_value',
+ hint: expect.stringContaining(file),
})
})
-it('rejects a newer schema_version with exit 6', async () => {
- writeFileSync(join(dir, 'config.yml'), 'schema_version: 2\n')
- const c = await new Context().get(config)
- await expect(c.get()).rejects.toMatchObject({ code: 'config_schema_unsupported' })
+it('loads a difyctl v1 file and drops its defaults and state on the next set', async () => {
+ writeFileSync(
+ file,
+ 'schema_version: 1\ndefaults:\n format: json\nstate:\n current_app: app-1\nhttp:\n timeout: 5000\n',
+ )
+ const c = await load()
+ expect(await c.get('http.timeout')).toBe(5000)
+ await c.set('http.timeout', '6000')
+ expect(readFileSync(file, 'utf8')).toBe('http:\n timeout: 6000\n')
+ expect(streams.errBuf()).toBe('')
+})
+
+it('ignores unknown and future keys without a notice', async () => {
+ writeFileSync(file, 'schema_version: 99\nfuture_key: x\nhttp:\n timeout: 5000\n later: 1\n')
+ const c = await load()
+ expect(await c.get()).toEqual({ http: { timeout: 5000 }, path: file })
+ expect(streams.errBuf()).toBe('')
+})
+
+it('falls back to the default for an invalid value, naming the key', async () => {
+ writeFileSync(file, 'http:\n timeout: fast\n')
+ const c = await load()
+ expect(await c.get('http.timeout')).toBe(30_000)
+ expect(streams.errBuf()).toBe(`${file}: ignoring the invalid value of http.timeout\n`)
+})
+
+it.each([
+ ['not valid YAML', 'http: [unclosed\n', /is not valid YAML/],
+ ['not a mapping', '- a\n- b\n', /is not a YAML mapping/],
+])('reads a file that is %s as empty and replaces it on the next set', async (_l, raw, note) => {
+ writeFileSync(file, raw)
+ const c = await load()
+ expect(await c.get('http.timeout')).toBe(30_000)
+ expect(streams.errBuf()).toMatch(note)
+ await c.set('http.timeout', '5000')
+ expect(readFileSync(file, 'utf8')).toBe('http:\n timeout: 5000\n')
})
diff --git a/cli/src/plugins/config/index.ts b/cli/src/plugins/config/index.ts
index f857d3cbd34..37ab1b22afa 100644
--- a/cli/src/plugins/config/index.ts
+++ b/cli/src/plugins/config/index.ts
@@ -5,18 +5,15 @@ import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { definePlugin } from '@/kernel/plugin'
import { env } from '@/plugins/env'
-import { YamlStore } from '@/store/store'
+import { io } from '@/plugins/io'
+import { localFile } from '@/store/local-file'
import { isRecord } from '@/util/is-record'
export const CONFIG_FILE_NAME = 'config.yml'
-export const CONFIG_SCHEMA_VERSION = 1
-export const CONFIG_SCHEMA = z
- .object({
- schema_version: z.literal(1).default(1),
- http: z.object({ timeout: z.number().int().positive().default(30_000) }).prefault({}),
- })
- .strict()
+const CONFIG_SCHEMA = z.object({
+ http: z.object({ timeout: z.number().int().positive().default(30_000) }).prefault({}),
+})
export type ConfigDoc = z.infer<typeof CONFIG_SCHEMA>
@@ -84,25 +81,13 @@ function parseRawValue(raw: string): unknown {
}
}
-function checkSchemaVersion(raw: unknown): void {
- if (!isRecord(raw)) return
- const version = raw.schema_version
- if (typeof version === 'number' && version > CONFIG_SCHEMA_VERSION) {
- throw new BaseError({
- code: ErrorCode.ConfigSchemaUnsupported,
- message: `config schema_version ${version} is newer than the supported version ${CONFIG_SCHEMA_VERSION}`,
- hint: 'upgrade difyctl to read this config file',
- })
- }
-}
-
-function validateDoc(raw: unknown): ConfigDoc {
- checkSchemaVersion(raw)
+function validateDoc(raw: unknown, path: string): ConfigDoc {
const result = CONFIG_SCHEMA.safeParse(raw)
if (!result.success) {
throw new BaseError({
code: ErrorCode.ConfigInvalidValue,
message: result.error.issues.map((issue) => issue.message).join('; '),
+ hint: `the value was not saved to ${path}`,
})
}
return result.data
@@ -110,27 +95,23 @@ function validateDoc(raw: unknown): ConfigDoc {
export const config = definePlugin({
name: 'config',
- needs: [env],
+ needs: [env, io],
build: async (ctx): Promise<ConfigService> => {
- const { configDir } = await ctx.get(env)
- const path = join(configDir, CONFIG_FILE_NAME)
- const store = new YamlStore(path)
+ const path = join((await ctx.get(env)).configDir, CONFIG_FILE_NAME)
+ const file = localFile(path, CONFIG_SCHEMA, (await ctx.get(io)).notice)
let cached: ConfigDoc | undefined
async function doc(): Promise<ConfigDoc> {
- if (cached === undefined) {
- const raw = await store.getTyped<Record<string, unknown>>()
- cached = validateDoc(raw ?? {})
- }
+ if (cached === undefined) cached = (await file.read()) ?? CONFIG_SCHEMA.parse({})
return cached
}
async function persist(mutate: (target: Record<string, unknown>) => void): Promise<void> {
const current = structuredClone(await doc()) as Record<string, unknown>
mutate(current)
- const validated = validateDoc(current)
- await store.setTyped(validated)
+ const validated = validateDoc(current, path)
+ await file.write(validated)
cached = validated
}
diff --git a/cli/src/plugins/env/index.test.ts b/cli/src/plugins/env/index.test.ts
index 493e0150d39..d81e71b9f37 100644
--- a/cli/src/plugins/env/index.test.ts
+++ b/cli/src/plugins/env/index.test.ts
@@ -23,6 +23,17 @@ it('rejects a token without a server with exit 2', async () => {
await expect(new Context().get(env)).rejects.toMatchObject({ code: 'usage_invalid_flag' })
})
+it('names the rename when the v1 DIFY_HOST stands in for DIFY_SERVER', async () => {
+ delete process.env.DIFY_SERVER
+ process.env.DIFY_HOST = 'https://dify.example'
+ process.env.DIFY_TOKEN = 'dfoa_x'
+ await expect(new Context().get(env)).rejects.toMatchObject({
+ code: 'usage_invalid_flag',
+ message: 'DIFY_TOKEN requires DIFY_SERVER to be set',
+ hint: 'DIFY_HOST was renamed to DIFY_SERVER; set DIFY_SERVER instead',
+ })
+})
+
it('rejects a non-http server url', async () => {
process.env.DIFY_SERVER = 'ftp://x'
await expect(new Context().get(env)).rejects.toMatchObject({ code: 'usage_invalid_flag' })
diff --git a/cli/src/plugins/env/index.ts b/cli/src/plugins/env/index.ts
index 7c21d43ba8e..793f37ae432 100644
--- a/cli/src/plugins/env/index.ts
+++ b/cli/src/plugins/env/index.ts
@@ -1,7 +1,7 @@
import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { definePlugin } from '@/kernel/plugin'
-import { resolveCacheDir, resolveConfigDir } from '@/store/dir'
+import { resolveConfigDir } from '@/store/dir'
import { getEnv } from '@/sys'
export const ENV = {
@@ -9,8 +9,11 @@ export const ENV = {
Token: 'DIFY_TOKEN',
WorkspaceId: 'DIFY_WORKSPACE_ID',
ConfigDir: 'DIFY_CONFIG_DIR',
- CacheDir: 'DIFY_CACHE_DIR',
Output: 'DIFY_OUTPUT',
+ // No longer read: the catalog lives in the config folder. Read only to say so.
+ CacheDir: 'DIFY_CACHE_DIR',
+ // difyctl v1's name for DIFY_SERVER; read only to name the rename.
+ V1Host: 'DIFY_HOST',
} as const
export type EnvService = Readonly<{
@@ -18,7 +21,7 @@ export type EnvService = Readonly<{
token?: string
workspaceId?: string
configDir: string
- cacheDir: string
+ cacheDirSet: boolean
}>
const HTTP_SCHEMES: readonly string[] = ['http:', 'https:']
@@ -54,6 +57,10 @@ export const env = definePlugin({
throw new BaseError({
code: ErrorCode.UsageInvalidFlag,
message: `${ENV.Token} requires ${ENV.Server} to be set`,
+ hint:
+ getEnv(ENV.V1Host) === undefined
+ ? undefined
+ : `${ENV.V1Host} was renamed to ${ENV.Server}; set ${ENV.Server} instead`,
})
}
return Object.freeze({
@@ -61,7 +68,7 @@ export const env = definePlugin({
token,
workspaceId: getEnv(ENV.WorkspaceId),
configDir: resolveConfigDir(),
- cacheDir: resolveCacheDir(),
+ cacheDirSet: getEnv(ENV.CacheDir) !== undefined,
})
},
})
diff --git a/cli/src/plugins/global-flags/index.ts b/cli/src/plugins/global-flags/index.ts
index 57a61f1faa0..050e8fb4770 100644
--- a/cli/src/plugins/global-flags/index.ts
+++ b/cli/src/plugins/global-flags/index.ts
@@ -4,6 +4,7 @@ import { ErrorCode } from '@/errors/codes'
import { definePlugin } from '@/kernel/plugin'
import { argv } from '@/plugins/argv'
import { inputSchema, parseArgv, partitionArgv } from '@/plugins/argv/parse'
+import { flagToken } from '@/util/flag-name'
export const GLOBAL_INPUT = z.object({
verbose: z.boolean().default(false).describe('Keep the raw server response in error envelopes'),
@@ -21,7 +22,7 @@ const NO_POSITIONALS: readonly string[] = []
function invalidGlobalFlags(error: z.ZodError): BaseError {
const message = error.issues
- .map((issue) => `--${issue.path.join('.')}: ${issue.message}`)
+ .map((issue) => `${flagToken(issue.path.join('.'))}: ${issue.message}`)
.join('; ')
return new BaseError({ code: ErrorCode.UsageInvalidFlag, message, cause: error })
}
diff --git a/cli/src/plugins/http/index.test.ts b/cli/src/plugins/http/index.test.ts
index b3195ee5b0f..f48dcf447a2 100644
--- a/cli/src/plugins/http/index.test.ts
+++ b/cli/src/plugins/http/index.test.ts
@@ -2,7 +2,7 @@ import type { DifyMock } from '@test/fixtures/dify-mock/server'
import { mkdtempSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
-import { startMock } from '@test/fixtures/dify-mock/server'
+import { FORBIDDEN_HINT, startMock } from '@test/fixtures/dify-mock/server'
import { afterEach, beforeEach, describe, expect, it } from 'vite-plus/test'
import { Context } from '@/kernel/context'
import { catalog, CATALOG_PATH } from '@/plugins/catalog'
@@ -15,22 +15,20 @@ let mock: DifyMock
let dir: string
function writeTimeout(ms: number): void {
- writeFileSync(join(dir, CONFIG_FILE_NAME), `schema_version: 1\nhttp:\n timeout: ${ms}\n`)
+ writeFileSync(join(dir, CONFIG_FILE_NAME), `http:\n timeout: ${ms}\n`)
}
beforeEach(async () => {
mock = await startMock()
dir = mkdtempSync(join(tmpdir(), 'difyctl-http-'))
Object.assign(process.env, {
DIFY_CONFIG_DIR: dir,
- DIFY_CACHE_DIR: dir,
DIFY_SERVER: mock.url,
DIFY_TOKEN: 'dfoa_test',
})
})
afterEach(async () => {
await mock.stop()
- for (const k of ['DIFY_CONFIG_DIR', 'DIFY_CACHE_DIR', 'DIFY_SERVER', 'DIFY_TOKEN'])
- delete process.env[k]
+ for (const k of ['DIFY_CONFIG_DIR', 'DIFY_SERVER', 'DIFY_TOKEN']) delete process.env[k]
})
const account = () => ({ method: 'GET', path: '/openapi/v1/account' })
@@ -103,6 +101,35 @@ describe('http plugin', () => {
await expect(h.request(account)).rejects.toMatchObject({ code: 'rate_limited' })
})
+ it('a 401 says to log in again', async () => {
+ const h = await new Context().get(http)
+ mock.setScenario('auth-expired')
+ await expect(h.request(account)).rejects.toMatchObject({ hint: 'run difyctl help login' })
+ })
+
+ it("a 403 keeps the server's hint and never says to log in", async () => {
+ const h = await new Context().get(http)
+ mock.setScenario('forbidden')
+ await expect(h.request(account)).rejects.toMatchObject({
+ code: 'access_denied',
+ message: 'you may not do this',
+ hint: FORBIDDEN_HINT,
+ })
+ })
+
+ it('a 403 without a server hint says permission denied', async () => {
+ process.env.DIFY_TOKEN = 'sk-test-resource'
+ const h = await new Context().get(http)
+ mock.setScenario('resource-token')
+ await expect(
+ h.request(() => ({ method: 'GET', path: '/openapi/v1/account' })),
+ ).rejects.toMatchObject({
+ code: 'access_denied',
+ httpStatus: 403,
+ hint: expect.stringMatching(/^permission denied/),
+ })
+ })
+
it('surfaces 5xx as server_error with the server body and details', async () => {
const h = await new Context().get(http)
mock.setScenario('server-5xx')
@@ -166,7 +193,7 @@ describe('http plugin', () => {
await expect((await new Context().get(http)).request(account)).rejects.toMatchObject({
code: 'catalog_unavailable',
message: `failed to fetch the catalog: HTTP 404 from ${CATALOG_PATH}`,
- hint: expect.stringContaining('refresh cache'),
+ hint: expect.stringContaining('server is reachable'),
})
})
diff --git a/cli/src/plugins/http/index.ts b/cli/src/plugins/http/index.ts
index 1b19931889a..6128f6d747f 100644
--- a/cli/src/plugins/http/index.ts
+++ b/cli/src/plugins/http/index.ts
@@ -12,6 +12,7 @@ import { config } from '@/plugins/config'
import { env } from '@/plugins/env'
import { session } from '@/plugins/session'
import { token } from '@/plugins/token'
+import { parseHints } from '@/protocol/hint'
import { userAgent } from '@/version/info'
export type HttpRequest = Readonly<{
@@ -40,7 +41,9 @@ const HttpStatus = {
const CATALOG_STALE_CODE = 'catalog_stale'
const CATALOG_UNAVAILABLE_PREFIX = 'failed to fetch the catalog: '
-const CATALOG_UNAVAILABLE_HINT = 'check the server URL or run difyctl refresh cache'
+// `refresh cache` would only repeat the fetch that failed, so it is not suggested.
+const CATALOG_UNAVAILABLE_HINT =
+ 'check that the saved server URL is right and the server is reachable, then retry'
// The catalog fetch is the CLI's first request, so its failure has to name itself:
// a rejected status for the catalog route, or whatever the network said.
@@ -50,11 +53,15 @@ function catalogFailure(cause: unknown): string {
return errorMessage(cause)
}
-type StatusMapping = Readonly<{ code: ErrorCodeValue; hint?: string }>
+const PERMISSION_DENIED_HINT = 'permission denied: this account may not do this'
+
+// `hint` replaces the server's hint; `fallbackHint` only fills in when it sent none.
+type StatusMapping = Readonly<{ code: ErrorCodeValue; hint?: string; fallbackHint?: string }>
const STATUS_MAPPINGS: Readonly<Record<number, StatusMapping>> = {
[HttpStatus.Unauthorized]: { code: ErrorCode.AuthExpired, hint: LOGIN_HINT },
- [HttpStatus.Forbidden]: { code: ErrorCode.AccessDenied, hint: LOGIN_HINT },
+ // Logging in again does not grant a permission, and `login` revokes the session first.
+ [HttpStatus.Forbidden]: { code: ErrorCode.AccessDenied, fallbackHint: PERMISSION_DENIED_HINT },
[HttpStatus.TooManyRequests]: { code: ErrorCode.RateLimited },
}
@@ -75,7 +82,8 @@ function parseServerErrorBody(raw: string): ServerErrorBody | undefined {
if (record.code !== undefined && typeof record.code !== 'string') return undefined
const message = typeof record.message === 'string' ? record.message : record.error
if (typeof message !== 'string') return undefined
- return { ...record, message } as ServerErrorBody
+ const body = { ...record, message } as ServerErrorBody
+ return record.hints === undefined ? body : { ...body, hints: parseHints(record.hints) }
}
function appendQuery(url: URL, query: HttpRequest['query']): void {
@@ -194,11 +202,11 @@ export const http = definePlugin({
const rawResponse = await res.text()
const serverError = parseServerErrorBody(rawResponse)
- const { code, hint } = classifyStatus(res)
+ const { code, hint, fallbackHint } = classifyStatus(res)
throw new HttpClientError({
code,
message: serverError?.message ?? `HTTP ${res.status}`,
- hint: hint ?? serverError?.hint,
+ hint: hint ?? serverError?.hint ?? fallbackHint,
httpStatus: res.status,
method: req.method,
url: url.toString(),
diff --git a/cli/src/plugins/ops/command.ts b/cli/src/plugins/ops/command.ts
index 9420ded7c8f..ef7e88e2405 100644
--- a/cli/src/plugins/ops/command.ts
+++ b/cli/src/plugins/ops/command.ts
@@ -58,7 +58,6 @@ export function opCommand(id: string, op: CatalogOp): CommandConstructor {
return class OpCommand extends Command {
static override summary = op.summary
static override effect = effectOf(op.method)
- static override positional = [] as const
static override examples = op.examples
static override hidden = op.internal
diff --git a/cli/src/plugins/ops/tree.ts b/cli/src/plugins/ops/tree.ts
index 791533dc809..286d26d32a5 100644
--- a/cli/src/plugins/ops/tree.ts
+++ b/cli/src/plugins/ops/tree.ts
@@ -1,7 +1,7 @@
import type { CatalogOp } from '@/plugins/catalog'
import type { CommandConstructor } from '@/plugins/commands/command'
import type { CommandTree } from '@/plugins/commands/registry'
-import { OP_SEPARATOR } from '@/protocol/op-id'
+import { commandWords } from '@/protocol/op-id'
import { opCommand } from './command'
// A node is readonly once it is in a tree; building one needs a mutable view of it.
@@ -10,7 +10,7 @@ type BuildingNode = { command?: CommandConstructor; subcommands: Record<string,
export function opsTree(ops: Readonly<Record<string, CatalogOp>>): CommandTree {
const tree: Record<string, BuildingNode> = {}
for (const [id, op] of Object.entries(ops)) {
- const segments = id.split(OP_SEPARATOR)
+ const segments = commandWords(id)
let level = tree
for (const [index, segment] of segments.entries()) {
const node = (level[segment] ??= { subcommands: {} })
diff --git a/cli/src/plugins/session/index.test.ts b/cli/src/plugins/session/index.test.ts
index 4e5cae8888c..df39442dea3 100644
--- a/cli/src/plugins/session/index.test.ts
+++ b/cli/src/plugins/session/index.test.ts
@@ -1,10 +1,12 @@
import type { Login } from './index'
-import { mkdtempSync } from 'node:fs'
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, expect, it } from 'vite-plus/test'
import { Context } from '@/kernel/context'
-import { session } from './index'
+import { io, ioService } from '@/plugins/io'
+import { bufferStreams } from '@/sys/io/streams'
+import { LOGIN_FILE_NAME, session } from './index'
const LOGIN: Login = {
server: 'https://d.example',
@@ -65,3 +67,43 @@ it('DIFY_WORKSPACE_ID overrides the pin', async () => {
process.env.DIFY_WORKSPACE_ID = 'ws-env'
expect(await (await new Context().get(session)).workspaceId()).toBe('ws-env')
})
+
+function withLoginFile(content: string) {
+ writeFileSync(join(dir, LOGIN_FILE_NAME), content)
+ const streams = bufferStreams()
+ return { streams, load: () => new Context([[io, ioService(streams)]]).get(session) }
+}
+
+it.each([
+ ['server', 'email: me@x\ntoken_storage: file\n'],
+ ['email', 'server: https://d.example\ntoken_storage: file\n'],
+])('reads a login.yml without %s as logged out, with one notice', async (key, content) => {
+ const { streams, load } = withLoginFile(content)
+ const s = await load()
+ expect(await s.current()).toBeNull()
+ expect(await s.current()).toBeNull()
+ expect(streams.errBuf()).toMatch(new RegExp(`has no valid ${key}; ignoring it\n$`))
+ await s.save(LOGIN)
+ expect(await s.current()).toEqual(LOGIN)
+})
+
+it('reads a login.yml with only its identity, defaulting the rest and ignoring unknown keys', async () => {
+ const { streams, load } = withLoginFile(
+ 'schema_version: 99\nfuture_key: x\nserver: https://d.example\nemail: me@x\ntoken_storage: file\ninsecure: maybe\n',
+ )
+ expect(await (await load()).current()).toEqual({
+ server: 'https://d.example',
+ email: 'me@x',
+ account: null,
+ workspaceId: null,
+ tokenStorage: 'file',
+ insecure: false,
+ })
+ expect(streams.errBuf()).toMatch(/ignoring the invalid value of insecure\n$/)
+})
+
+it('saves only the current shape', async () => {
+ const { load } = withLoginFile('future_key: x\n')
+ await (await load()).save(LOGIN)
+ expect(readFileSync(join(dir, LOGIN_FILE_NAME), 'utf8')).not.toContain('future_key')
+})
diff --git a/cli/src/plugins/session/index.ts b/cli/src/plugins/session/index.ts
index ae49873108f..0316c35ee03 100644
--- a/cli/src/plugins/session/index.ts
+++ b/cli/src/plugins/session/index.ts
@@ -4,26 +4,27 @@ import { z } from 'zod'
import { BaseError, notLoggedIn } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
import { definePlugin } from '@/kernel/plugin'
-import { env } from '@/plugins/env'
-import { STORAGE_MODES, YamlStore } from '@/store/store'
+import { ENV, env } from '@/plugins/env'
+import { io } from '@/plugins/io'
+import { localFile } from '@/store/local-file'
+import { STORAGE_MODES } from '@/store/store'
export const LOGIN_FILE_NAME = 'login.yml'
-export const LOGIN_SCHEMA_VERSION = 1
export const ENV_LOGIN_EMAIL = 'env'
-const ACCOUNT_SCHEMA = z.object({ id: z.string(), email: z.string(), name: z.string() })
+const LOGIN_SCHEMA = z.object({
+ server: z.string(),
+ email: z.string(),
+ token_storage: z.enum(STORAGE_MODES),
+ account: z
+ .object({ id: z.string(), email: z.string(), name: z.string() })
+ .nullable()
+ .default(null),
+ workspace_id: z.string().nullable().default(null),
+ insecure: z.boolean().default(false),
+})
-const LOGIN_SCHEMA = z
- .object({
- schema_version: z.literal(LOGIN_SCHEMA_VERSION),
- server: z.string(),
- email: z.string(),
- account: ACCOUNT_SCHEMA.nullable(),
- workspace_id: z.string().nullable(),
- token_storage: z.enum(STORAGE_MODES),
- insecure: z.boolean(),
- })
- .strict()
+type LoginDoc = z.infer<typeof LOGIN_SCHEMA>
export type Login = Readonly<{
server: string
@@ -43,9 +44,8 @@ export type SessionService = {
readonly fromEnv: boolean
}
-function loginToDoc(login: Login): z.infer<typeof LOGIN_SCHEMA> {
+function loginToDoc(login: Login): LoginDoc {
return {
- schema_version: LOGIN_SCHEMA_VERSION,
server: login.server,
email: login.email,
account: login.account,
@@ -55,7 +55,7 @@ function loginToDoc(login: Login): z.infer<typeof LOGIN_SCHEMA> {
}
}
-function docToLogin(doc: z.infer<typeof LOGIN_SCHEMA>): Login {
+function docToLogin(doc: LoginDoc): Login {
return {
server: doc.server,
email: doc.email,
@@ -68,13 +68,16 @@ function docToLogin(doc: z.infer<typeof LOGIN_SCHEMA>): Login {
export const session = definePlugin({
name: 'session',
- needs: [env],
+ needs: [env, io],
build: async (ctx): Promise<SessionService> => {
const { server, token: envToken, workspaceId: envWorkspaceId, configDir } = await ctx.get(env)
// An env login is the pair: a server on its own only says where to log in.
const fromEnv = server !== undefined && envToken !== undefined
- const path = join(configDir, LOGIN_FILE_NAME)
- const store = new YamlStore(path)
+ const file = localFile(
+ join(configDir, LOGIN_FILE_NAME),
+ LOGIN_SCHEMA,
+ (await ctx.get(io)).notice,
+ )
const envLogin: Login | null = fromEnv
? {
@@ -87,17 +90,13 @@ export const session = definePlugin({
}
: null
+ // Read once: a broken file warns on its first read only.
+ let saved: Login | null | undefined
async function readLogin(): Promise<Login | null> {
- const raw = await store.getTyped<unknown>()
- if (raw === null) return null
- const result = LOGIN_SCHEMA.safeParse(raw)
- if (!result.success) {
- throw new BaseError({
- code: ErrorCode.Unknown,
- message: `${path} failed validation: ${result.error.issues.map((issue) => issue.message).join('; ')}`,
- })
- }
- return docToLogin(result.data)
+ if (saved !== undefined) return saved
+ const doc = await file.read()
+ saved = doc === null ? null : docToLogin(doc)
+ return saved
}
const current = async (): Promise<Login | null> => envLogin ?? readLogin()
@@ -106,7 +105,8 @@ export const session = definePlugin({
current,
require: async () => {
const login = await current()
- if (login === null) throw notLoggedIn()
+ if (login === null)
+ throw notLoggedIn(`no login saved in ${configDir}; ${ENV.ConfigDir} picks this folder`)
return login
},
save: async (login: Login) => {
@@ -116,11 +116,13 @@ export const session = definePlugin({
message: 'cannot save a login while DIFY_SERVER/DIFY_TOKEN are set',
})
}
- await store.setTyped(loginToDoc(login))
+ await file.write(loginToDoc(login))
+ saved = login
},
clear: async () => {
if (fromEnv) return
- await store.rm()
+ await file.remove()
+ saved = null
},
workspaceId: async () => {
if (envWorkspaceId !== undefined) return envWorkspaceId
diff --git a/cli/src/plugins/token/index.ts b/cli/src/plugins/token/index.ts
index e8fdb874be1..735ca940d9c 100644
--- a/cli/src/plugins/token/index.ts
+++ b/cli/src/plugins/token/index.ts
@@ -1,12 +1,19 @@
import type { Login } from '@/plugins/session'
import type { StorageMode } from '@/store/store'
+import type { TokenStore } from '@/store/token-store'
+import { join } from 'node:path'
import { notLoggedIn } from '@/errors/base'
import { definePlugin } from '@/kernel/plugin'
import { env } from '@/plugins/env'
+import { io } from '@/plugins/io'
import { session } from '@/plugins/session'
+import { localFile } from '@/store/local-file'
import { detectTokenStore, getTokenStore } from '@/store/manager'
+import { TOKENS_SCHEMA } from '@/store/token-store'
import { bareHost } from '@/util/host'
+export const TOKENS_FILE_NAME = 'tokens.yml'
+
export type DetectOptions = Readonly<{ skipKeyring: boolean }>
export type TokenService = {
@@ -14,21 +21,28 @@ export type TokenService = {
readonly write: (login: Login, bearer: string) => Promise<void>
readonly remove: (login: Login) => Promise<void>
readonly detect: (opts: DetectOptions) => Promise<StorageMode>
+ readonly store: (mode: StorageMode) => TokenStore
}
export const token = definePlugin({
name: 'token',
- needs: [env, session],
+ needs: [env, session, io],
build: async (ctx): Promise<TokenService> => {
- const { token: envToken } = await ctx.get(env)
+ const { token: envToken, configDir } = await ctx.get(env)
const sessionService = await ctx.get(session)
+ const file = localFile(
+ join(configDir, TOKENS_FILE_NAME),
+ TOKENS_SCHEMA,
+ (await ctx.get(io)).notice,
+ )
let cached: string | undefined
+ const store = (mode: StorageMode): TokenStore => getTokenStore(mode, { file })
+
async function readFromStore(): Promise<string> {
const login = await sessionService.require()
- const store = getTokenStore(login.tokenStorage)
- return store.read(bareHost(login.server), login.email)
+ return store(login.tokenStorage).read(bareHost(login.server), login.email)
}
return {
@@ -39,16 +53,15 @@ export const token = definePlugin({
return cached
},
write: async (login: Login, bearer: string) => {
- const store = getTokenStore(login.tokenStorage)
- await store.write(bareHost(login.server), login.email, bearer)
+ await store(login.tokenStorage).write(bareHost(login.server), login.email, bearer)
cached = bearer
},
remove: async (login: Login) => {
- const store = getTokenStore(login.tokenStorage)
- await store.remove(bareHost(login.server), login.email)
+ await store(login.tokenStorage).remove(bareHost(login.server), login.email)
cached = ''
},
- detect: async (opts) => (await detectTokenStore(opts)).mode,
+ detect: async (opts) => (await detectTokenStore({ ...opts, file })).mode,
+ store,
}
},
})
diff --git a/cli/src/protocol/fold.ts b/cli/src/protocol/fold.ts
index 225f582ce2d..e4b66b7bafb 100644
--- a/cli/src/protocol/fold.ts
+++ b/cli/src/protocol/fold.ts
@@ -1,12 +1,7 @@
+import type { Hint } from '@/protocol/hint'
+import { parseHints } from '@/protocol/hint'
import { isRecord } from '@/util/is-record'
-export type Hint = {
- summary: string
- op: string
- input: Record<string, unknown>
- form?: unknown
-}
-
export type FoldResult = {
status: FoldStatus
text: { answer: string; by_source?: Record<string, string> }
@@ -14,6 +9,7 @@ export type FoldResult = {
total_tokens?: number
message_id?: string
conversation_id?: string
+ run_id?: string
error?: { message: string; code?: string }
hints: Hint[]
}
@@ -51,7 +47,7 @@ function asString(value: unknown): string | undefined {
}
function appendHints(result: FoldResult, hints: unknown): void {
- if (Array.isArray(hints)) result.hints.push(...(hints as Hint[]))
+ result.hints.push(...parseHints(hints))
}
function appendAnswer(result: FoldResult, event: Record<string, unknown>): void {
@@ -113,6 +109,12 @@ function markError(result: FoldResult, event: Record<string, unknown>): void {
raise(result, FOLD_STATUS.Failed)
}
+/** Runs for every event before its own handler: any workflow event names its run. */
+export const foldAnyEvent: EventHandler = (result, event) => {
+ const runId = asString(event.workflow_run_id)
+ if (runId !== undefined) result.run_id = runId
+}
+
export const FOLD_TABLE: Readonly<Record<string, EventHandler>> = Object.freeze({
message: appendAnswer,
agent_message: appendAnswer,
diff --git a/cli/src/protocol/hint.test.ts b/cli/src/protocol/hint.test.ts
new file mode 100644
index 00000000000..2ff29565a69
--- /dev/null
+++ b/cli/src/protocol/hint.test.ts
@@ -0,0 +1,16 @@
+import { expect, it } from 'vite-plus/test'
+import { parseHints } from './hint'
+
+it('keeps only hints with a string op and summary', () => {
+ const good = { op: 'get.app', summary: 'list apps', input: {} }
+ expect(parseHints([good, { summary: 'no op' }, { op: 1, summary: 'x' }, 'text', null])).toEqual([
+ good,
+ ])
+})
+
+it.each([undefined, null, 'hints', { op: 'get.app', summary: 'x' }])(
+ 'reads %j as no hints',
+ (value) => {
+ expect(parseHints(value)).toEqual([])
+ },
+)
diff --git a/cli/src/protocol/hint.ts b/cli/src/protocol/hint.ts
new file mode 100644
index 00000000000..9708c810616
--- /dev/null
+++ b/cli/src/protocol/hint.ts
@@ -0,0 +1,16 @@
+import { isRecord } from '@/util/is-record'
+
+export type Hint = {
+ summary: string
+ op: string
+ input?: Record<string, unknown>
+ form?: unknown
+}
+
+function isHint(value: unknown): value is Hint {
+ return isRecord(value) && typeof value.op === 'string' && typeof value.summary === 'string'
+}
+
+export function parseHints(value: unknown): Hint[] {
+ return Array.isArray(value) ? value.filter(isHint) : []
+}
diff --git a/cli/src/protocol/op-id.ts b/cli/src/protocol/op-id.ts
index 308621a81f9..9a35cb58c80 100644
--- a/cli/src/protocol/op-id.ts
+++ b/cli/src/protocol/op-id.ts
@@ -1,9 +1,13 @@
export const OP_SEPARATOR = '.'
export const COMMAND_SEPARATOR = ' '
+export function commandWords(id: string): readonly string[] {
+ return id.split(OP_SEPARATOR)
+}
+
/** An op id as the words it is typed as: `get.console_app` -> `get console_app`. */
export function spacedId(id: string): string {
- return id.split(OP_SEPARATOR).join(COMMAND_SEPARATOR)
+ return commandWords(id).join(COMMAND_SEPARATOR)
}
export function dottedId(path: readonly string[]): string {
diff --git a/cli/src/protocol/shape.test.ts b/cli/src/protocol/shape.test.ts
index 99847da1ff0..7dd81587884 100644
--- a/cli/src/protocol/shape.test.ts
+++ b/cli/src/protocol/shape.test.ts
@@ -18,7 +18,9 @@ it.each([
[nullable({ type: 'string', enum: ['x'] }), SHAPE.Enum, 'x'],
[{ enum: [] }, SHAPE.Json, 'json'],
[{ type: 'string', enum: [] }, SHAPE.Json, 'json'],
- [{ oneOf: [{ type: 'string' }, { type: 'integer' }] }, SHAPE.Json, 'json'],
+ [{ oneOf: [{ type: 'string' }, { type: 'integer' }] }, SHAPE.Union, 'string | integer'],
+ [{ anyOf: [{ type: 'string' }, { type: 'integer' }] }, SHAPE.Union, 'string | integer'],
+ [{ anyOf: [{ type: 'string' }], oneOf: [{ type: 'integer' }] }, SHAPE.Json, 'json'],
[{ someFutureKeyword: true }, SHAPE.Json, 'json'],
])('%j classifies as %s labelled %s', (schema, shape, label) => {
const node = shapeOf(schema)
diff --git a/cli/src/protocol/shape.ts b/cli/src/protocol/shape.ts
index 325f06e47e9..f2cce705d58 100644
--- a/cli/src/protocol/shape.ts
+++ b/cli/src/protocol/shape.ts
@@ -12,9 +12,15 @@ export const SHAPE = {
Map: 'map',
Object: 'object',
Json: 'json',
+ Union: 'union',
} as const
export type Shape = (typeof SHAPE)[keyof typeof SHAPE]
-export type ShapeNode = Readonly<{ shape: Shape; item?: ShapeNode; values?: readonly string[] }>
+export type ShapeNode = Readonly<{
+ shape: Shape
+ item?: ShapeNode
+ values?: readonly string[]
+ alternatives?: readonly ShapeNode[]
+}>
type Coercion = (raw: string) => unknown
@@ -24,7 +30,7 @@ const ARRAY_TYPE = 'array'
const OBJECT_TYPE = 'object'
const STRING_TYPE = 'string'
const FILE_REF_PREFIX = '@'
-const ENUM_SEPARATOR = ' | '
+const ALTERNATIVE_SEPARATOR = ' | '
const BOOLEAN_LITERALS: Readonly<Record<string, boolean>> = { true: true, false: false }
const keepRaw: Coercion = (raw) => raw
@@ -64,7 +70,7 @@ const SHAPE_INFO: Readonly<Record<Shape, ShapeInfo>> = {
[SHAPE.Number]: { label: () => SHAPE.Number, coerce: () => toNumber, scalar: true },
[SHAPE.Boolean]: { label: () => SHAPE.Boolean, coerce: () => toBoolean, scalar: true },
[SHAPE.Enum]: {
- label: (n) => (n.values ?? []).join(ENUM_SEPARATOR),
+ label: (n) => (n.values ?? []).join(ALTERNATIVE_SEPARATOR),
coerce: () => keepRaw,
scalar: true,
},
@@ -81,19 +87,28 @@ const SHAPE_INFO: Readonly<Record<Shape, ShapeInfo>> = {
},
[SHAPE.Object]: { label: () => SHAPE.Object, coerce: () => toJson, scalar: false },
[SHAPE.Json]: { label: () => SHAPE.Json, coerce: () => toJson, scalar: false },
+ [SHAPE.Union]: {
+ label: (n) => (n.alternatives ?? []).map(labelOf).join(ALTERNATIVE_SEPARATOR),
+ coerce: () => toJson,
+ scalar: false,
+ },
}
-// pydantic optional: anyOf [T, null]. Anything else with anyOf is json.
-function unwrapNullable(schema: JsonSchema): JsonSchema | undefined {
- const branches = schema.anyOf
- if (!Array.isArray(branches) || branches.length !== 2) return undefined
- const real = branches.filter((b) => !(isRecord(b) && b.type === NULL_TYPE))
- return real.length === 1 && isRecord(real[0]) ? (real[0] as JsonSchema) : undefined
+// One list of branches, from anyOf or oneOf. A schema with both is not one union, so it
+// reads as no alternatives and falls through to its type.
+function alternativesOf(schema: JsonSchema): JsonSchema[] {
+ const lists = [schema.anyOf, schema.oneOf].filter(Array.isArray)
+ const [branches] = lists
+ if (lists.length !== 1 || branches === undefined) return []
+ return branches.filter((b) => isRecord(b) && b.type !== NULL_TYPE) as JsonSchema[]
}
export function shapeOf(schema: JsonSchema): ShapeNode {
- const inner = unwrapNullable(schema)
- if (inner !== undefined) return shapeOf(inner)
+ const alternatives = alternativesOf(schema)
+ const [only] = alternatives
+ if (alternatives.length === 1 && only !== undefined) return shapeOf(only)
+ if (alternatives.length > 1)
+ return { shape: SHAPE.Union, alternatives: alternatives.map(shapeOf) }
const type = typeof schema.type === 'string' ? schema.type : undefined
// An enum with no members names no value at all, so it degrades to json rather than
// labelling as the empty string.
diff --git a/cli/src/skills/collection.ts b/cli/src/skills/collection.ts
deleted file mode 100644
index 88bf0918ba3..00000000000
--- a/cli/src/skills/collection.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-import type { SkillEntry, SkillSource } from './source'
-import { posix } from 'node:path'
-import { BaseError } from '@/errors/base'
-import { ErrorCode } from '@/errors/codes'
-import { parseFrontmatter } from './frontmatter'
-import { SKILL_FILE } from './source'
-
-export const BASIC_SKILL = 'difyctl'
-const ROOT_DIR = '.'
-const SKILL_NAME_RE = /^[a-z0-9-]{1,64}$/
-
-export type Skill = {
- readonly name: string
- readonly description: string
- readonly dir: string
- readonly files: readonly SkillEntry[]
-}
-
-function skillDirs(entries: readonly SkillEntry[]): string[] {
- const dirs = entries
- .filter(
- (entry) => entry.path.split('/').length <= 2 && posix.basename(entry.path) === SKILL_FILE,
- )
- .map((entry) => posix.dirname(entry.path))
- return dirs.includes(ROOT_DIR) ? [ROOT_DIR] : dirs
-}
-
-function filesIn(entries: readonly SkillEntry[], dir: string): SkillEntry[] {
- return entries
- .filter((entry) => dir === ROOT_DIR || entry.path.startsWith(`${dir}/`))
- .map((entry) => ({
- ...entry,
- path: dir === ROOT_DIR ? entry.path : entry.path.slice(dir.length + 1),
- }))
-}
-
-async function loadSkill(source: SkillSource, dir: string): Promise<Skill> {
- const path = posix.join(dir, SKILL_FILE)
- const meta = parseFrontmatter(new TextDecoder().decode(await source.read(path)))
- const { name, description } = meta
- if (typeof name !== 'string' || !SKILL_NAME_RE.test(name) || typeof description !== 'string') {
- throw new BaseError({
- code: ErrorCode.ServerError,
- message: `${path}: frontmatter needs a name (lowercase letters, digits, dashes) and a description`,
- })
- }
- return { name, description, dir, files: filesIn(source.entries, dir) }
-}
-
-export async function loadSkills(source: SkillSource): Promise<Skill[]> {
- const skills = await Promise.all(skillDirs(source.entries).map((dir) => loadSkill(source, dir)))
- if (skills.length === 0) {
- throw new BaseError({
- code: ErrorCode.UsageInvalidFlag,
- message: 'no skills found',
- hint: 'point --from at a folder of skills, or at one skill folder',
- })
- }
- return skills
-}
-
-export function isScenario(skill: Skill): boolean {
- return skill.name !== BASIC_SKILL
-}
-
-export function findSkill(skills: readonly Skill[], name: string): Skill {
- const skill = skills.find((candidate) => candidate.name === name)
- if (skill === undefined) {
- throw new BaseError({
- code: ErrorCode.UsageInvalidFlag,
- message: `unknown skill "${name}"`,
- hint: `known skills: ${skills.map((candidate) => candidate.name).join(', ')}`,
- })
- }
- return skill
-}
diff --git a/cli/src/skills/frontmatter.ts b/cli/src/skills/frontmatter.ts
deleted file mode 100644
index adcdc0885f7..00000000000
--- a/cli/src/skills/frontmatter.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { load } from 'js-yaml'
-import { isRecord } from '@/util/is-record'
-
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/
-
-export type Frontmatter = { readonly head: string; readonly body: string }
-
-export function splitFrontmatter(text: string): Frontmatter | undefined {
- const match = FRONTMATTER_RE.exec(text)
- if (match === null) return undefined
- return { head: match[1] as string, body: text.slice(match[0].length) }
-}
-
-export function parseFrontmatter(text: string): Record<string, unknown> {
- const split = splitFrontmatter(text)
- if (split === undefined) return {}
- const doc: unknown = load(split.head)
- return isRecord(doc) ? doc : {}
-}
diff --git a/cli/src/skills/github.ts b/cli/src/skills/github.ts
deleted file mode 100644
index 6a5c9901dd9..00000000000
--- a/cli/src/skills/github.ts
+++ /dev/null
@@ -1,112 +0,0 @@
-import type { SkillSource } from './source'
-import { createHash } from 'node:crypto'
-import { z } from 'zod'
-import { BaseError } from '@/errors/base'
-import { ErrorCode } from '@/errors/codes'
-import { buildFetchInit } from '@/net/fetch-init'
-import { proxyDispatcher } from '@/net/proxy'
-import { getEnv } from '@/sys'
-
-export const GITHUB_ORIGIN = 'https://github.com'
-const API_ORIGIN = 'https://api.github.com'
-const RAW_ORIGIN = 'https://raw.githubusercontent.com'
-const TREE_SEGMENT = 'tree'
-const DEFAULT_REF = 'HEAD'
-const TOKEN_ENV = 'GITHUB_TOKEN'
-const RATE_LIMIT_HEADER = 'x-ratelimit-remaining'
-const TOO_MANY_REQUESTS = 429
-const EXECUTABLE_MODE = '100755'
-const FILE_MODES: readonly string[] = ['100644', EXECUTABLE_MODE]
-const FROM_HINT = 'check --from, or download the skills folder and pass --from <folder>'
-
-const TREE_SCHEMA = z.object({
- truncated: z.boolean(),
- tree: z.array(z.object({ path: z.string(), mode: z.string(), sha: z.string() })),
-})
-
-export type GitHubFolder = {
- readonly owner: string
- readonly repo: string
- readonly ref: string
- readonly path: string
-}
-
-export function parseGitHubUrl(url: string): GitHubFolder {
- const [owner, repo, segment, ref, ...rest] = new URL(url).pathname.split('/').filter(Boolean)
- const tree = segment === undefined || (segment === TREE_SEGMENT && ref !== undefined)
- if (owner === undefined || repo === undefined || !tree) {
- throw new BaseError({
- code: ErrorCode.UsageInvalidFlag,
- message: `unsupported GitHub URL "${url}"`,
- hint: `use ${GITHUB_ORIGIN}/<owner>/<repo>/tree/<ref>/<folder>`,
- })
- }
- return { owner, repo, ref: ref ?? DEFAULT_REF, path: rest.join('/') }
-}
-
-async function get(url: string, token?: string): Promise<Response> {
- const headers = token === undefined ? undefined : { authorization: `Bearer ${token}` }
- let res: Response
- try {
- res = await fetch(
- url,
- buildFetchInit({ headers }, { insecure: false, dispatcher: proxyDispatcher() }),
- )
- } catch (cause) {
- throw new BaseError({
- code: ErrorCode.NetworkConnection,
- message: `GET ${url} failed`,
- hint: FROM_HINT,
- cause,
- })
- }
- if (res.ok) return res
- const limited = res.status === TOO_MANY_REQUESTS || res.headers.get(RATE_LIMIT_HEADER) === '0'
- throw new BaseError({
- code: limited ? ErrorCode.RateLimited : ErrorCode.ServerError,
- message: `GET ${url} returned ${res.status}`,
- hint: limited ? `set ${TOKEN_ENV} to raise GitHub's rate limit, or ${FROM_HINT}` : FROM_HINT,
- })
-}
-
-function gitBlobSha(bytes: Uint8Array): string {
- return createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex')
-}
-
-export async function openGitHub(url: string): Promise<SkillSource> {
- const { owner, repo, ref, path } = parseGitHubUrl(url)
- const treeUrl = `${API_ORIGIN}/repos/${owner}/${repo}/git/trees/${encodeURIComponent(`${ref}:${path}`)}?recursive=1`
- const parsed = TREE_SCHEMA.safeParse(await (await get(treeUrl, getEnv(TOKEN_ENV))).json())
- if (!parsed.success)
- throw new BaseError({
- code: ErrorCode.ServerError,
- message: `unexpected response from ${treeUrl}`,
- })
- if (parsed.data.truncated) {
- throw new BaseError({
- code: ErrorCode.UsageInvalidFlag,
- message: `${url} holds too many files to list`,
- hint: 'point --from at the skills folder',
- })
- }
- const files = parsed.data.tree.filter((entry) => FILE_MODES.includes(entry.mode))
- const shas = new Map(files.map((entry) => [entry.path, entry.sha]))
- return {
- entries: files.map((entry) => ({
- path: entry.path,
- executable: entry.mode === EXECUTABLE_MODE,
- })),
- read: async (file) => {
- const rawUrl = [RAW_ORIGIN, owner, repo, ref, path, file].filter(Boolean).join('/')
- const bytes = new Uint8Array(await (await get(rawUrl)).arrayBuffer())
- if (gitBlobSha(bytes) !== shas.get(file)) {
- throw new BaseError({
- code: ErrorCode.ServerError,
- message: `${rawUrl} changed during the install`,
- hint: 'retry in a few minutes',
- })
- }
- return bytes
- },
- }
-}
diff --git a/cli/src/skills/install.test.ts b/cli/src/skills/install.test.ts
index 0f04c9a2e94..7fa38052b14 100644
--- a/cli/src/skills/install.test.ts
+++ b/cli/src/skills/install.test.ts
@@ -1,13 +1,9 @@
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { chmod, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { platform, tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
-import { afterEach, beforeEach, describe, expect, it } from 'vite-plus/test'
-import { ErrorCode } from '@/errors/codes'
-import { BASIC_SKILL, loadSkills } from './collection'
-import { installSkills, selectSkills } from './install'
-import { openSource } from './source'
-
-const SCENARIO = 'difyctl-demo'
+import { afterEach, beforeEach, expect, it } from 'vite-plus/test'
+import { installSkill } from './install'
+import { openDir, SKILL_FILE, SKILL_NAME } from './source'
let tmp: string
let from: string
@@ -19,47 +15,32 @@ async function put(path: string, text: string): Promise<void> {
await writeFile(abs, text)
}
-function skillMd(name: string): string {
- return `---\nname: ${name}\ndescription: ${name} skill\n---\n\n# ${name}\n`
-}
-
beforeEach(async () => {
- tmp = await mkdtemp(join(tmpdir(), 'difyctl-skills-'))
+ tmp = await mkdtemp(join(tmpdir(), 'difyctl-skill-'))
from = join(tmp, 'source')
root = join(tmp, 'root')
- await put(`${BASIC_SKILL}/SKILL.md`, skillMd(BASIC_SKILL))
- await put(`${SCENARIO}/SKILL.md`, skillMd(SCENARIO))
+ await put(SKILL_FILE, `---\nname: ${SKILL_NAME}\ndescription: d\n---\n`)
+ await put('references/setup.md', 'setup')
})
afterEach(async () => {
await rm(tmp, { recursive: true, force: true })
})
-describe('selectSkills', () => {
- it('selects the whole collection when no names are given', async () => {
- const skills = await loadSkills(await openSource(from))
- expect(selectSkills(skills, [])).toEqual(skills)
- })
-
- it('selects the named skills', async () => {
- const skills = await loadSkills(await openSource(from))
- expect(selectSkills(skills, [BASIC_SKILL]).map((s) => s.name)).toEqual([BASIC_SKILL])
- })
-
- it('rejects an unknown name as a usage error', async () => {
- const skills = await loadSkills(await openSource(from))
- expect(() => selectSkills(skills, ['nope'])).toThrow(
- expect.objectContaining({ code: ErrorCode.UsageInvalidFlag }),
- )
- })
+it('writes every file under <root>/difyctl', async () => {
+ const wrote = await installSkill(root, await openDir(from))
+ expect(wrote.sort()).toEqual(
+ [join(root, SKILL_NAME, SKILL_FILE), join(root, SKILL_NAME, 'references/setup.md')].sort(),
+ )
+ expect(await readFile(join(root, SKILL_NAME, 'references/setup.md'), 'utf8')).toBe('setup')
})
-describe('installSkills', () => {
- it('writes <root>/<skill>/<file> for every file of every skill', async () => {
- const source = await openSource(from)
- const basic = selectSkills(await loadSkills(source), [BASIC_SKILL])
- const target = join(root, BASIC_SKILL, 'SKILL.md')
- expect(await installSkills(root, basic, source)).toEqual([target])
- expect(await readFile(target, 'utf8')).toBe(skillMd(BASIC_SKILL))
- })
-})
+it.skipIf(platform() === 'win32')(
+ 'keeps the permission bits of files from a local folder',
+ async () => {
+ await put('scripts/run', 'no shebang')
+ await chmod(join(from, 'scripts/run'), 0o755)
+ await installSkill(root, await openDir(from))
+ expect((await stat(join(root, SKILL_NAME, 'scripts/run'))).mode & 0o111).toBe(0o111)
+ },
+)
diff --git a/cli/src/skills/install.ts b/cli/src/skills/install.ts
index 858be55d546..e28825e49cd 100644
--- a/cli/src/skills/install.ts
+++ b/cli/src/skills/install.ts
@@ -1,37 +1,20 @@
-import type { Skill } from './collection'
import type { SkillSource } from './source'
import { mkdir, rm, writeFile } from 'node:fs/promises'
-import { dirname, join, posix } from 'node:path'
-import { BASIC_SKILL, findSkill, isScenario } from './collection'
+import { dirname, join } from 'node:path'
+import { SKILL_NAME } from './source'
-const FILE_MODE = 0o644
-const EXECUTABLE_MODE = 0o755
-
-export function selectSkills(skills: readonly Skill[], names: readonly string[]): Skill[] {
- if (names.length === 0) return [...skills]
- const chosen = new Map(names.map((name) => [name, findSkill(skills, name)]))
- const basic = skills.find((skill) => skill.name === BASIC_SKILL)
- if (basic !== undefined && [...chosen.values()].some(isScenario)) chosen.set(BASIC_SKILL, basic)
- return [...chosen.values()]
-}
-
-export async function installSkills(
- root: string,
- skills: readonly Skill[],
- source: SkillSource,
-): Promise<string[]> {
- const downloads = []
- for (const skill of skills) {
- for (const file of skill.files)
- downloads.push({ skill, file, bytes: await source.read(posix.join(skill.dir, file.path)) })
- }
- for (const skill of skills) await rm(join(root, skill.name), { recursive: true, force: true })
+export async function installSkill(root: string, source: SkillSource): Promise<string[]> {
+ const files = await Promise.all(
+ source.paths.map(async (path) => ({ path, file: await source.read(path) })),
+ )
+ const target = join(root, SKILL_NAME)
+ await rm(target, { recursive: true, force: true })
const wrote: string[] = []
- for (const { skill, file, bytes } of downloads) {
- const path = join(root, skill.name, file.path)
- await mkdir(dirname(path), { recursive: true })
- await writeFile(path, bytes, { mode: file.executable ? EXECUTABLE_MODE : FILE_MODE })
- wrote.push(path)
+ for (const { path, file } of files) {
+ const abs = join(target, path)
+ await mkdir(dirname(abs), { recursive: true })
+ await writeFile(abs, file.bytes, { mode: file.mode })
+ wrote.push(abs)
}
return wrote
}
diff --git a/cli/src/skills/source.ts b/cli/src/skills/source.ts
index 2dc2c33ca9f..63ff4cf65a3 100644
--- a/cli/src/skills/source.ts
+++ b/cli/src/skills/source.ts
@@ -1,76 +1,94 @@
-import type { Dirent } from 'node:fs'
+import type { EmbeddedFile } from '@/sys'
import { readdir, readFile, stat } from 'node:fs/promises'
import { join, relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
import { z } from 'zod'
import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
-import { versionInfo } from '@/version/info'
-import { GITHUB_ORIGIN, openGitHub } from './github'
+import { embeddedFiles, isCompiledBinary } from '@/sys'
+export const SKILL_NAME = 'difyctl'
export const SKILL_FILE = 'SKILL.md'
-const EXECUTABLE_BITS = 0o111
-const URL_RE = /^https?:\/\//
+const EMBED_PREFIX = `${SKILL_NAME}/`
+const REPO_SKILL_DIR = fileURLToPath(new URL(`../../../skills/${EMBED_PREFIX}`, import.meta.url))
+const NO_EMBEDDED_SKILL =
+ 'this difyctl build has no embedded skill; reinstall difyctl or pass --from <folder>'
-export type SkillEntry = { readonly path: string; readonly executable: boolean }
+const EXECUTABLE_MODE = 0o755
+const FILE_MODE = 0o644
+const PERMISSION_BITS = 0o777
+const SHEBANG = [0x23, 0x21]
+
+export type SkillFile = {
+ readonly bytes: Uint8Array
+ readonly mode: number
+}
export type SkillSource = {
- readonly entries: readonly SkillEntry[]
- readonly read: (path: string) => Promise<Uint8Array>
+ readonly paths: readonly string[]
+ readonly read: (path: string) => Promise<SkillFile>
}
-export const DEFAULT_SOURCE = `${GITHUB_ORIGIN}/langgenius/dify/tree/${versionInfo.commit}/skills`
+// Embedded files carry no permission bits, so a script is recognised by its shebang.
+function embeddedMode(bytes: Uint8Array): number {
+ return SHEBANG.every((byte, i) => bytes[i] === byte) ? EXECUTABLE_MODE : FILE_MODE
+}
+
+async function readLocal(abs: string): Promise<SkillFile> {
+ const [bytes, info] = await Promise.all([readFile(abs), stat(abs)])
+ return { bytes, mode: info.mode & PERMISSION_BITS }
+}
export const FROM_FIELD = z
.string()
.min(1)
- .default(DEFAULT_SOURCE)
- .describe('Where the skills come from: a GitHub folder URL or a local folder')
+ .optional()
+ .describe('A local skill folder to install instead of the one built into difyctl')
-async function hasSkillFile(dir: string): Promise<boolean> {
- return stat(join(dir, SKILL_FILE)).then(
+export async function openDir(root: string): Promise<SkillSource> {
+ const found = await stat(join(root, SKILL_FILE)).then(
() => true,
() => false,
)
-}
-
-async function walk(root: string, dir: string): Promise<SkillEntry[]> {
- const entries: SkillEntry[] = []
- for (const entry of await readdir(dir, { recursive: true, withFileTypes: true })) {
- if (!entry.isFile()) continue
- const abs = join(entry.parentPath, entry.name)
- const executable = ((await stat(abs)).mode & EXECUTABLE_BITS) !== 0
- entries.push({ path: relative(root, abs).split(sep).join('/'), executable })
- }
- return entries
-}
-
-async function openDir(root: string): Promise<SkillSource> {
- let children: Dirent[]
- try {
- children = await readdir(root, { withFileTypes: true })
- } catch (cause) {
+ if (!found) {
throw new BaseError({
code: ErrorCode.UsageInvalidFlag,
- message: `cannot read folder "${root}"`,
- cause,
+ message: `no ${SKILL_FILE} in "${root}"`,
})
}
- const dirs = (await hasSkillFile(root))
- ? [root]
- : children.filter((child) => child.isDirectory()).map((child) => join(root, child.name))
- const entries: SkillEntry[] = []
- for (const dir of dirs) if (await hasSkillFile(dir)) entries.push(...(await walk(root, dir)))
- return { entries, read: (path) => readFile(join(root, path)) }
+ const paths: string[] = []
+ for (const entry of await readdir(root, { recursive: true, withFileTypes: true })) {
+ if (entry.isFile())
+ paths.push(relative(root, join(entry.parentPath, entry.name)).split(sep).join('/'))
+ }
+ return { paths, read: (path) => readLocal(join(root, path)) }
}
-export function openSource(from: string): Promise<SkillSource> {
- if (from.startsWith(`${GITHUB_ORIGIN}/`)) return openGitHub(from)
- if (URL_RE.test(from)) {
- throw new BaseError({
- code: ErrorCode.UsageInvalidFlag,
- message: `unsupported --from URL "${from}"`,
- hint: `use a ${GITHUB_ORIGIN} folder URL or a local folder`,
- })
+function embeddedSource(files: readonly EmbeddedFile[]): SkillSource {
+ const byPath = new Map(files.map((file) => [file.name.slice(EMBED_PREFIX.length), file]))
+ return {
+ paths: [...byPath.keys()],
+ read: async (path) => {
+ const file = byPath.get(path)
+ if (file === undefined)
+ throw new BaseError({
+ code: ErrorCode.SkillMissing,
+ message: `the embedded skill has no ${path}`,
+ })
+ const bytes = new Uint8Array(await file.arrayBuffer())
+ return { bytes, mode: embeddedMode(bytes) }
+ },
}
- return openDir(from)
+}
+
+async function defaultSource(): Promise<SkillSource> {
+ const files = embeddedFiles().filter((file) => file.name.startsWith(EMBED_PREFIX))
+ if (files.length > 0) return embeddedSource(files)
+ if (isCompiledBinary())
+ throw new BaseError({ code: ErrorCode.SkillMissing, message: NO_EMBEDDED_SKILL })
+ return openDir(REPO_SKILL_DIR)
+}
+
+export function openSource(from: string | undefined): Promise<SkillSource> {
+ return from === undefined ? defaultSource() : openDir(from)
}
diff --git a/cli/src/store/dir.ts b/cli/src/store/dir.ts
index 3917417e28b..e7e7465db35 100644
--- a/cli/src/store/dir.ts
+++ b/cli/src/store/dir.ts
@@ -1,16 +1,9 @@
import { getEnv, resolvePlatform } from '@/sys'
export const ENV_CONFIG_DIR = 'DIFY_CONFIG_DIR'
-export const ENV_CACHE_DIR = 'DIFY_CACHE_DIR'
export const FILE_PERM = 0o600
export const DIR_PERM = 0o700
-export function resolveCacheDir(): string {
- const override = getEnv(ENV_CACHE_DIR)
- if (override !== undefined && override !== '') return override
- return resolvePlatform().cacheDir()
-}
-
export function resolveConfigDir(): string {
const override = getEnv(ENV_CONFIG_DIR)
if (override !== undefined && override !== '') return override
diff --git a/cli/src/store/keychain-token-store.test.ts b/cli/src/store/keychain-token-store.test.ts
index 685660b3e9e..879b599a069 100644
--- a/cli/src/store/keychain-token-store.test.ts
+++ b/cli/src/store/keychain-token-store.test.ts
@@ -72,7 +72,7 @@ describe('KeychainTokenStore', () => {
await expect(store.remove('h', 'absent')).resolves.not.toThrow()
})
- it('uses the legacy entry name tokens.<host>.<email> (back-compat)', async () => {
+ it('names the entry tokens.<host>.<email>', async () => {
const store = new KeychainTokenStore(SERVICE)
await store.write('https://cloud.dify.ai', '[email protected]', 'dfoa_secret')
expect(constructed).toContainEqual({
@@ -131,3 +131,11 @@ describe('KeychainTokenStore', () => {
expect((caught as BaseError).code).toBe(ErrorCode.KeyringUnavailable)
})
})
+
+it('a locked keychain points at login --no-keyring', async () => {
+ getPasswordError = new Error('keyring locked')
+ await expect(new KeychainTokenStore(SERVICE).read('h', 'e')).rejects.toMatchObject({
+ code: ErrorCode.KeyringUnavailable,
+ hint: expect.stringContaining('login --server <url> --no-keyring'),
+ })
+})
diff --git a/cli/src/store/keyring-based-store.test.ts b/cli/src/store/keyring-based-store.test.ts
deleted file mode 100644
index df11d3832e1..00000000000
--- a/cli/src/store/keyring-based-store.test.ts
+++ /dev/null
@@ -1,102 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'
-
-const passwords = new Map<string, string>()
-const setPassword = vi.fn()
-const getPassword = vi.fn()
-const deletePassword = vi.fn()
-
-class FakeEntry {
- private readonly key: string
- constructor(service: string, username: string) {
- this.key = `${service}::${username}`
- }
-
- async setPassword(value: string): Promise<void> {
- setPassword(this.key, value)
- passwords.set(this.key, value)
- }
-
- async getPassword(): Promise<string | undefined> {
- getPassword(this.key)
- return passwords.get(this.key) ?? undefined
- }
-
- async deletePassword(): Promise<boolean> {
- deletePassword(this.key)
- if (!passwords.has(this.key)) return false
- passwords.delete(this.key)
- return true
- }
-}
-
-vi.mock('@napi-rs/keyring', () => ({
- AsyncEntry: FakeEntry,
-}))
-
-const { KeyringBasedStore } = await import('./store')
-
-const SERVICE = 'difyctl-test'
-
-beforeEach(() => {
- passwords.clear()
- setPassword.mockClear()
- getPassword.mockClear()
- deletePassword.mockClear()
-})
-
-describe('KeyringBasedStore', () => {
- it('returns default when entry missing', async () => {
- const s = new KeyringBasedStore(SERVICE)
- expect(await s.get({ key: 'k', default: 'fallback' })).toBe('fallback')
- })
-
- it('round-trips strings via JSON encoding', async () => {
- const s = new KeyringBasedStore(SERVICE)
- await s.set({ key: 'k', default: '' }, 'tok-abc')
- expect(await s.get({ key: 'k', default: '' })).toBe('tok-abc')
- })
-
- it('isolates entries by key', async () => {
- const s = new KeyringBasedStore(SERVICE)
- await s.set({ key: 'a', default: '' }, 'A')
- await s.set({ key: 'b', default: '' }, 'B')
- expect(await s.get({ key: 'a', default: '' })).toBe('A')
- expect(await s.get({ key: 'b', default: '' })).toBe('B')
- })
-
- it('unset removes the entry', async () => {
- const s = new KeyringBasedStore(SERVICE)
- await s.set({ key: 'k', default: '' }, 'v')
- await s.unset({ key: 'k', default: '' })
- expect(await s.get({ key: 'k', default: '' })).toBe('')
- })
-
- it('unset is a no-op when entry missing', async () => {
- const s = new KeyringBasedStore(SERVICE)
- await expect(s.unset({ key: 'gone', default: '' })).resolves.not.toThrow()
- })
-
- it('swallows getPassword exceptions and returns default', async () => {
- const s = new KeyringBasedStore(SERVICE)
- getPassword.mockImplementationOnce(() => {
- throw new Error('NoEntry')
- })
- expect(await s.get({ key: 'k', default: 'd' })).toBe('d')
- })
-
- it('swallows unset exceptions', async () => {
- const s = new KeyringBasedStore(SERVICE)
- deletePassword.mockImplementationOnce(() => {
- throw new Error('NoEntry')
- })
- await expect(s.unset({ key: 'k', default: '' })).resolves.not.toThrow()
- })
-
- it('lets set propagate exceptions (caller decides fallback)', async () => {
- const s = new KeyringBasedStore(SERVICE)
- setPassword.mockImplementationOnce(() => {
- throw new Error('keyring locked')
- })
- await expect(s.set({ key: 'k', default: '' }, 'v')).rejects.toThrow(/keyring locked/)
- })
-})
diff --git a/cli/src/store/local-file.test.ts b/cli/src/store/local-file.test.ts
new file mode 100644
index 00000000000..efd3b0a85d8
--- /dev/null
+++ b/cli/src/store/local-file.test.ts
@@ -0,0 +1,71 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, expect, it } from 'vite-plus/test'
+import { z } from 'zod'
+import { localFile } from './local-file'
+
+const SCHEMA = z.object({ name: z.string(), size: z.number().default(1) })
+
+let dir: string
+let path: string
+beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), 'difyctl-local-file-'))
+ path = join(dir, 'doc.yml')
+})
+afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+it('writes the whole file in the schema shape, dropping keys the schema does not know', async () => {
+ const file = localFile(path, SCHEMA, () => {})
+ await file.write({ name: 'a', size: 2, legacy: true } as z.output<typeof SCHEMA>)
+ expect(readFileSync(path, 'utf8')).toBe('name: a\nsize: 2\n')
+})
+
+it('refuses to write a document the schema rejects', async () => {
+ const file = localFile(path, SCHEMA, () => {})
+ await expect(file.write({ name: 1 } as unknown as z.output<typeof SCHEMA>)).rejects.toThrow()
+ expect(await file.read()).toBeNull()
+})
+
+const NESTED = z.object({
+ host: z.string(),
+ account: z.object({ id: z.string(), name: z.string() }).optional(),
+ tags: z.array(z.object({ key: z.string() })).default([]),
+})
+
+function readNested(yaml: string) {
+ writeFileSync(path, yaml)
+ const notices: string[] = []
+ return { notices, doc: localFile(path, NESTED, (text) => notices.push(text)).read() }
+}
+
+it('drops a bad nested leaf by dropping the nearest value that exists on its path', async () => {
+ const { notices, doc } = readNested('host: h\naccount:\n id: 1\n name: n\n')
+ expect(await doc).toEqual({ host: 'h', tags: [] })
+ expect(notices).toEqual([
+ `${path}: ignoring the invalid value of account.id`,
+ `${path}: ignoring the invalid value of account`,
+ ])
+})
+
+it('drops an optional parent whose required key is missing', async () => {
+ const { notices, doc } = readNested('host: h\naccount:\n id: a\n')
+ expect(await doc).toEqual({ host: 'h', tags: [] })
+ expect(notices).toEqual([`${path}: ignoring the invalid value of account`])
+})
+
+it('drops only the bad items of an array', async () => {
+ const { doc } = readNested('host: h\ntags:\n - key: a\n - key: 2\n - {}\n - key: d\n')
+ expect(await doc).toEqual({ host: 'h', tags: [{ key: 'a' }, { key: 'd' }] })
+})
+
+it('drops a parent that is not a mapping at all', async () => {
+ const { doc } = readNested('host: h\naccount: plain\n')
+ expect(await doc).toEqual({ host: 'h', tags: [] })
+})
+
+it('ignores the file when a required top-level key is missing', async () => {
+ const { notices, doc } = readNested('account:\n id: a\n name: n\n')
+ expect(await doc).toBeNull()
+ expect(notices).toEqual([`${path} has no valid host; ignoring it`])
+})
diff --git a/cli/src/store/local-file.ts b/cli/src/store/local-file.ts
new file mode 100644
index 00000000000..1b250f609e5
--- /dev/null
+++ b/cli/src/store/local-file.ts
@@ -0,0 +1,96 @@
+import type { z } from 'zod'
+import { isRecord } from '@/util/is-record'
+import { BadYamlFormatError } from './errors'
+import { YamlStore } from './store'
+
+export type Notice = (text: string) => void
+
+type Path = readonly PropertyKey[]
+
+function childOf(container: unknown, key: PropertyKey): unknown {
+ if (Array.isArray(container) && typeof key === 'number') return container[key]
+ return isRecord(container) && Object.hasOwn(container, key) ? container[key as string] : undefined
+}
+
+// The longest prefix of `path` that names a value in `doc`; empty when not even the
+// first key exists.
+function existing(doc: Record<string, unknown>, path: Path): Path {
+ let at: unknown = doc
+ for (const [depth, key] of path.entries()) {
+ const child = childOf(at, key)
+ if (child === undefined) return path.slice(0, depth)
+ at = child
+ }
+ return path
+}
+
+function remove(doc: Record<string, unknown>, path: Path): void {
+ const last = path.at(-1)
+ const parent = path.slice(0, -1).reduce<unknown>(childOf, doc)
+ if (Array.isArray(parent)) parent.splice(last as number, 1)
+ else if (isRecord(parent)) delete parent[last as string]
+}
+
+async function readTolerant<S extends z.ZodType>(
+ store: YamlStore,
+ schema: S,
+ notice: Notice,
+): Promise<z.output<S> | null> {
+ const path = store.filePath
+ let raw: unknown
+ try {
+ raw = await store.getTyped<unknown>()
+ } catch (err) {
+ if (!(err instanceof BadYamlFormatError)) throw err
+ notice(`${path} is not valid YAML; ignoring it`)
+ return null
+ }
+ if (raw === null) return null
+ if (!isRecord(raw)) {
+ notice(`${path} is not a YAML mapping; ignoring it`)
+ return null
+ }
+ const doc = structuredClone(raw)
+ // One drop per pass: an earlier drop can resolve, move or shift a later issue's path.
+ for (;;) {
+ const result = schema.safeParse(doc)
+ if (result.success) return result.data
+ const keys = result.error.issues.map((issue) => issue.path)
+ const droppable = keys.map((key) => existing(doc, key)).find((key) => key.length > 0)
+ if (droppable === undefined) {
+ notice(`${path} has no valid ${keys.map((key) => key.join('.')).join(', ')}; ignoring it`)
+ return null
+ }
+ remove(doc, droppable)
+ notice(`${path}: ignoring the invalid value of ${droppable.join('.')}`)
+ }
+}
+
+export type LocalFile<T> = Readonly<{
+ path: string
+ read: () => Promise<T | null>
+ write: (doc: T) => Promise<void>
+ remove: () => Promise<void>
+ /** Remove the file only while it still holds a document `matches` accepts. */
+ removeIf: (matches: (doc: T) => boolean) => Promise<void>
+}>
+
+/** Tolerant read (bad value → default + notice; unusable file → null); write replaces the whole file. */
+export function localFile<S extends z.ZodType>(
+ path: string,
+ schema: S,
+ notice: Notice,
+): LocalFile<z.output<S>> {
+ const store = new YamlStore(path)
+ return {
+ path,
+ read: () => readTolerant(store, schema, notice),
+ write: async (doc) => store.setTyped(schema.parse(doc)),
+ remove: () => store.rm(),
+ removeIf: (matches) =>
+ store.rmIf((doc) => {
+ const parsed = schema.safeParse(doc)
+ return parsed.success && matches(parsed.data)
+ }),
+ }
+}
diff --git a/cli/src/store/manager.test.ts b/cli/src/store/manager.test.ts
index 43d534dbfba..f964214281d 100644
--- a/cli/src/store/manager.test.ts
+++ b/cli/src/store/manager.test.ts
@@ -1,6 +1,24 @@
import type { TokenStore } from './token-store'
-import { describe, expect, it, vi } from 'vite-plus/test'
-import { detectTokenStore, getTokenStore } from './manager'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'
+import { localFile } from './local-file'
+import { detectTokenStore, getTokenStore, keyringDurable } from './manager'
+import { TOKENS_SCHEMA } from './token-store'
+
+const DBUS_SESSION = 'DBUS_SESSION_BUS_ADDRESS'
+const sys = vi.hoisted(() => ({ platform: 'darwin' as NodeJS.Platform }))
+vi.mock('@/sys', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('@/sys')>()),
+ platform: () => sys.platform,
+}))
+
+const file = localFile('', TOKENS_SCHEMA, () => {})
+
+beforeEach(() => {
+ sys.platform = 'darwin'
+})
+afterEach(() => {
+ vi.unstubAllEnvs()
+})
function memStore(label: string): TokenStore & { _label: string } {
const map = new Map<string, string>()
@@ -25,6 +43,7 @@ describe('detectTokenStore', () => {
const f = memStore('file')
const writeSpy = vi.spyOn(k, 'write')
const result = await detectTokenStore({
+ file,
skipKeyring: true,
factory: { keyring: () => k, file: () => f },
})
@@ -37,6 +56,7 @@ describe('detectTokenStore', () => {
const k = memStore('keyring')
const f = memStore('file')
const result = await detectTokenStore({
+ file,
factory: { keyring: () => k, file: () => f },
})
expect(result.mode).toBe('keychain')
@@ -50,6 +70,7 @@ describe('detectTokenStore', () => {
throw new Error('locked')
}) as TokenStore['write']
const result = await detectTokenStore({
+ file,
factory: { keyring: () => k, file: () => f },
})
expect(result.mode).toBe('file')
@@ -61,6 +82,7 @@ describe('detectTokenStore', () => {
const f = memStore('file')
k.read = vi.fn(async () => 'something-else') as TokenStore['read']
const result = await detectTokenStore({
+ file,
factory: { keyring: () => k, file: () => f },
})
expect(result.mode).toBe('file')
@@ -70,6 +92,7 @@ describe('detectTokenStore', () => {
it('falls back to file when keyring constructor throws', async () => {
const f = memStore('file')
const result = await detectTokenStore({
+ file,
factory: {
keyring: () => {
throw new Error('no backend')
@@ -85,6 +108,7 @@ describe('detectTokenStore', () => {
const k = memStore('keyring')
const f = memStore('file')
await detectTokenStore({
+ file,
factory: { keyring: () => k, file: () => f },
})
expect(await k.read('__difyctl_probe__', '__difyctl_probe__')).toBe('')
@@ -98,6 +122,7 @@ describe('detectTokenStore', () => {
throw new Error('read boom')
}) as TokenStore['read']
const result = await detectTokenStore({
+ file,
factory: { keyring: () => k, file: () => f },
})
expect(removeSpy).toHaveBeenCalledWith('__difyctl_probe__', '__difyctl_probe__')
@@ -114,6 +139,7 @@ describe('getTokenStore', () => {
throw new Error('probe must never run on the read path')
}) as TokenStore['write']
const store = getTokenStore('keychain', {
+ file,
factory: { keyring: () => k, file: () => f },
})
expect(store).toBe(k)
@@ -123,9 +149,36 @@ describe('getTokenStore', () => {
const keyringFactory = vi.fn(() => memStore('keyring'))
const f = memStore('file')
const store = getTokenStore('file', {
+ file,
factory: { keyring: keyringFactory, file: () => f },
})
expect(store).toBe(f)
expect(keyringFactory).not.toHaveBeenCalled()
})
})
+
+describe('keyringDurable', () => {
+ it.each([
+ ['linux', undefined, false],
+ ['linux', '', false],
+ ['linux', 'unix:path=/run/user/1000/bus', true],
+ ['darwin', undefined, true],
+ ['win32', undefined, true],
+ ['freebsd', undefined, true],
+ ] as const)('%s with DBus %o → %s', (platform, dbus, durable) => {
+ sys.platform = platform
+ vi.stubEnv(DBUS_SESSION, dbus)
+ expect(keyringDurable()).toBe(durable)
+ })
+
+ it('a non-durable keyring skips the probe and uses the file store', async () => {
+ sys.platform = 'linux'
+ vi.stubEnv(DBUS_SESSION, undefined)
+ const k = memStore('keyring')
+ const f = memStore('file')
+ const writeSpy = vi.spyOn(k, 'write')
+ const result = await detectTokenStore({ file, factory: { keyring: () => k, file: () => f } })
+ expect(writeSpy).not.toHaveBeenCalled()
+ expect(result.mode).toBe('file')
+ })
+})
diff --git a/cli/src/store/manager.ts b/cli/src/store/manager.ts
index 86b78736a4a..8e8919f635f 100644
--- a/cli/src/store/manager.ts
+++ b/cli/src/store/manager.ts
@@ -1,28 +1,18 @@
import type { StorageMode } from './store'
-import type { TokenStore } from './token-store'
-import { join } from 'node:path'
-import { resolveConfigDir } from './dir'
-import { YamlStore } from './store'
+import type { TokensFile, TokenStore } from './token-store'
+import { getEnv, platform } from '@/sys'
import { FileTokenStore, KeychainTokenStore } from './token-store'
-const TOKENS_FILE = 'tokens.yml'
-export const CONFIG_FILE_NAME = 'config.yml'
-
const KEYRING_SERVICE = 'difyctl'
-
-function getStore(filePath: string): YamlStore {
- return new YamlStore(filePath)
-}
-
-export function getConfigurationStore(): YamlStore {
- return getStore(join(resolveConfigDir(), CONFIG_FILE_NAME))
-}
+const LINUX = 'linux'
+const DBUS_SESSION = 'DBUS_SESSION_BUS_ADDRESS'
const PROBE_HOST = '__difyctl_probe__'
const PROBE_EMAIL = '__difyctl_probe__'
const PROBE_VALUE = 'probe-v1'
export type GetTokenStoreOptions = {
+ readonly file: TokensFile
readonly factory?: {
readonly keyring?: () => TokenStore
readonly file?: () => TokenStore
@@ -33,9 +23,16 @@ export type DetectTokenStoreOptions = GetTokenStoreOptions & {
readonly skipKeyring?: boolean
}
+/**
+ * Without a DBus session, the Linux keyring falls back to the kernel keyutils
+ * store: the probe round-trips, but the token is gone when the session ends.
+ */
+export function keyringDurable(): boolean {
+ return platform() !== LINUX || Boolean(getEnv(DBUS_SESSION))
+}
+
const TOKEN_STORE_OPENERS: Record<StorageMode, (opts: GetTokenStoreOptions) => TokenStore> = {
- file: (opts) =>
- opts.factory?.file?.() ?? new FileTokenStore(join(resolveConfigDir(), TOKENS_FILE)),
+ file: (opts) => opts.factory?.file?.() ?? new FileTokenStore(opts.file),
keychain: (opts) => opts.factory?.keyring?.() ?? new KeychainTokenStore(KEYRING_SERVICE),
}
@@ -45,9 +42,10 @@ const TOKEN_STORE_OPENERS: Record<StorageMode, (opts: GetTokenStoreOptions) => T
* only where a credential is about to be written anyway (login).
*/
export async function detectTokenStore(
- opts: DetectTokenStoreOptions = {},
+ opts: DetectTokenStoreOptions,
): Promise<{ store: TokenStore; mode: StorageMode }> {
- if (opts.skipKeyring === true) return { store: TOKEN_STORE_OPENERS.file(opts), mode: 'file' }
+ if (opts.skipKeyring === true || !keyringDurable())
+ return { store: TOKEN_STORE_OPENERS.file(opts), mode: 'file' }
try {
const k = TOKEN_STORE_OPENERS.keychain(opts)
await k.write(PROBE_HOST, PROBE_EMAIL, PROBE_VALUE)
@@ -67,6 +65,6 @@ export async function detectTokenStore(
/**
* Construct the credential backend the registry already recorded at login.
*/
-export function getTokenStore(mode: StorageMode, opts: GetTokenStoreOptions = {}): TokenStore {
+export function getTokenStore(mode: StorageMode, opts: GetTokenStoreOptions): TokenStore {
return TOKEN_STORE_OPENERS[mode](opts)
}
diff --git a/cli/src/store/store.test.ts b/cli/src/store/store.test.ts
index 0bfaf7e8588..2660d7f6cff 100644
--- a/cli/src/store/store.test.ts
+++ b/cli/src/store/store.test.ts
@@ -1,116 +1,79 @@
-import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, statSync } from 'node:fs'
import { mkdtemp, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vite-plus/test'
-import { BadYamlFormatError, ConcurrentAccessError } from './errors'
+import { BadYamlFormatError } from './errors'
import { YamlStore } from './store'
-describe('YamlStore.doGet', () => {
- it('returns default when content is undefined', () => {
- const store = new YamlStore('/irrelevant')
- expect(store.doGet({ key: 'name', default: 'fallback' })).toBe('fallback')
- })
+let dir: string
+let path: string
- it('returns default when content is empty', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('')
- expect(store.doGet({ key: 'name', default: 'fallback' })).toBe('fallback')
- })
+beforeEach(async () => {
+ dir = await mkdtemp(join(tmpdir(), 'difyctl-yaml-store-'))
+ path = join(dir, 'config.yml')
+})
- it('returns default when content contains only comments', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('# empty configuration\n')
- expect(store.doGet({ key: 'name', default: 'fallback' })).toBe('fallback')
- })
+afterEach(async () => {
+ await rm(dir, { recursive: true, force: true })
+})
- it('reads a flat key', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('name: alice\n')
- expect(store.doGet({ key: 'name', default: '' })).toBe('alice')
- })
+async function parsed<T = Record<string, unknown>>(content: string): Promise<T | null> {
+ await writeFile(path, content)
+ return new YamlStore(path).getTyped<T>()
+}
- it('reads a nested key via dot notation', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('user:\n id: 42\n')
- expect(store.doGet({ key: 'user.id', default: 0 })).toBe(42)
+describe('YamlStore.getTyped', () => {
+ it('returns null when the file does not exist', async () => {
+ expect(await new YamlStore(path).getTyped()).toBeNull()
})
- it('resolves YAML merge keys', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('defaults: &defaults\n format: json\nselected:\n <<: *defaults\n')
- expect(store.doGet({ key: 'selected.format', default: '' })).toBe('json')
+ it('reads an empty or comment-only file as an empty mapping', async () => {
+ expect(await parsed('')).toEqual({})
+ expect(await parsed('# empty configuration\n')).toEqual({})
})
- it('parses timestamp scalars as dates', () => {
- const store = new YamlStore('/irrelevant')
- const timestamp = '2026-07-10T03:04:05.000Z'
- store.setRawContent(`created_at: ${timestamp}\n`)
- expect(store.doGet<Date | null>({ key: 'created_at', default: null })).toEqual(
- new Date(timestamp),
- )
+ it('reads nested mappings', async () => {
+ expect(await parsed('name: alice\nuser:\n id: 42\n')).toEqual({
+ name: 'alice',
+ user: { id: 42 },
+ })
})
- it('rejects multiple YAML documents', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('name: alice\n---\nname: bob\n')
-
- expect(() => store.doGet({ key: 'name', default: '' })).toThrowError(/single document/)
+ it('resolves YAML merge keys', async () => {
+ const doc = await parsed('defaults: &defaults\n format: json\nselected:\n <<: *defaults\n')
+ expect(doc?.selected).toEqual({ format: 'json' })
})
- it('rejects duplicate mapping keys', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('name: alice\nname: bob\n')
-
- expect(() => store.doGet({ key: 'name', default: '' })).toThrowError(/duplicated mapping key/)
- })
-
- it('rejects complex mapping keys', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('? [name, region]\n: deployment\n')
-
- expect(() => store.doGet({ key: 'name', default: '' })).toThrowError(
- /does not support complex keys/,
- )
+ it('parses timestamp scalars as dates', async () => {
+ const timestamp = '2026-07-10T03:04:05.000Z'
+ expect((await parsed(`created_at: ${timestamp}\n`))?.created_at).toEqual(new Date(timestamp))
})
- it('parses explicit YAML sets as JavaScript sets', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('features: !!set\n workflow:\n chat:\n')
-
- expect(store.doGet<Set<string>>({ key: 'features', default: new Set() })).toEqual(
+ it('parses explicit YAML sets as JavaScript sets', async () => {
+ expect((await parsed('features: !!set\n workflow:\n chat:\n'))?.features).toEqual(
new Set(['workflow', 'chat']),
)
})
- it('returns default for a missing flat key', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('name: alice\n')
- expect(store.doGet({ key: 'age', default: -1 })).toBe(-1)
+ it('rejects multiple YAML documents', async () => {
+ await expect(parsed('name: alice\n---\nname: bob\n')).rejects.toThrowError(/single document/)
})
- it('returns default when an intermediate path segment is absent', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('user:\n name: bob\n')
- expect(store.doGet({ key: 'user.address.city', default: 'unknown' })).toBe('unknown')
+ it('rejects duplicate mapping keys', async () => {
+ await expect(parsed('name: alice\nname: bob\n')).rejects.toThrowError(/duplicated mapping key/)
})
- it('returns default when an intermediate path segment is a scalar', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('user: scalar\n')
- expect(store.doGet({ key: 'user.id', default: 0 })).toBe(0)
+ it('rejects complex mapping keys', async () => {
+ await expect(parsed('? [name, region]\n: deployment\n')).rejects.toThrowError(
+ /does not support complex keys/,
+ )
})
- it('throws BadYamlFormatError with file path, location, and snippet for malformed YAML', () => {
- const path = '/irrelevant'
- const store = new YamlStore(path)
- store.setRawContent('name: alice\nuser:\n id: 42\n bad: indent\n')
- let caught: unknown
- try {
- store.doGet({ key: 'name', default: '' })
- } catch (err) {
- caught = err
- }
+ it('throws BadYamlFormatError with file path, location, and snippet for malformed YAML', async () => {
+ const caught = await parsed('name: alice\nuser:\n id: 42\n bad: indent\n').catch(
+ (err: unknown) => err,
+ )
expect(caught).toBeInstanceOf(BadYamlFormatError)
const msg = (caught as BadYamlFormatError).message
expect(msg).toContain(path)
@@ -119,143 +82,71 @@ describe('YamlStore.doGet', () => {
})
})
-describe('YamlStore.doSet', () => {
- it('sets a flat key from empty content', () => {
- const store = new YamlStore('/irrelevant')
- store.doSet({ key: 'name', default: '' }, 'alice')
- expect(store.doGet({ key: 'name', default: '' })).toBe('alice')
- })
-
- it('sets a nested key, creating intermediate objects', () => {
- const store = new YamlStore('/irrelevant')
- store.doSet({ key: 'user.id', default: 0 }, 42)
- expect(store.doGet({ key: 'user.id', default: 0 })).toBe(42)
- })
-
- it('overwrites an existing key without disturbing siblings', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('name: alice\nage: 30\n')
- store.doSet({ key: 'name', default: '' }, 'bob')
- expect(store.doGet({ key: 'name', default: '' })).toBe('bob')
- expect(store.doGet({ key: 'age', default: 0 })).toBe(30)
- })
-
- it('replaces a scalar intermediate with an object when path deepens', () => {
- const store = new YamlStore('/irrelevant')
- store.setRawContent('user: scalar\n')
- store.doSet({ key: 'user.id', default: 0 }, 99)
- expect(store.doGet({ key: 'user.id', default: 0 })).toBe(99)
- })
-})
-
-describe('FileBasedStore.withLock concurrency', () => {
- let dir: string
-
- beforeEach(async () => {
- dir = await mkdtemp(join(tmpdir(), 'difyctl-yaml-store-'))
- })
-
- afterEach(async () => {
- await rm(dir, { recursive: true, force: true })
- })
+describe('YamlStore.withLock concurrency', () => {
+ const HOLD_MS = 200
+ const releaseLater = (store: YamlStore) =>
+ new Promise<void>((resolve) => setTimeout(() => void store.unlock().then(resolve), HOLD_MS))
- it('second get throws while first holds the lock, succeeds after release', async () => {
- const path = join(dir, 'config.yml')
+ it('a second read waits while the first holds the lock, then reads', async () => {
await writeFile(path, 'key: value\n')
-
const s1 = new YamlStore(path)
const s2 = new YamlStore(path)
await s1.lock()
+ const [value] = await Promise.all([s2.getTyped(), releaseLater(s1)])
- await expect(s2.get({ key: 'key', default: '' })).rejects.toThrow(ConcurrentAccessError)
-
- await s1.unlock()
-
- expect(await s2.get({ key: 'key', default: '' })).toBe('value')
+ expect(value).toEqual({ key: 'value' })
})
- it('second set throws while first holds the lock, succeeds after release', async () => {
- const path = join(dir, 'config.yml')
+ it('a second write waits while the first holds the lock, then writes', async () => {
await writeFile(path, 'key: original\n')
-
const s1 = new YamlStore(path)
const s2 = new YamlStore(path)
await s1.lock()
+ await Promise.all([s2.setTyped({ key: 'written' }), releaseLater(s1)])
- await expect(s2.set({ key: 'key', default: '' }, 'blocked')).rejects.toThrow(
- ConcurrentAccessError,
- )
-
- await s1.unlock()
-
- await s2.set({ key: 'key', default: '' }, 'written')
- expect(await s2.get({ key: 'key', default: '' })).toBe('written')
+ expect(await s2.getTyped()).toEqual({ key: 'written' })
})
})
-describe('YamlStore persistence', () => {
- let dir: string
-
- beforeEach(async () => {
- dir = await mkdtemp(join(tmpdir(), 'difyctl-yaml-store-'))
+describe('YamlStore.rmIf', () => {
+ it('removes the file when the predicate accepts what it holds', async () => {
+ await writeFile(path, 'device_code: dc-1\n')
+ await new YamlStore(path).rmIf((doc) => doc?.device_code === 'dc-1')
+ expect(existsSync(path)).toBe(false)
})
- afterEach(async () => {
- await rm(dir, { recursive: true, force: true })
+ it('keeps the file when it holds something else', async () => {
+ await writeFile(path, 'device_code: dc-2\n')
+ await new YamlStore(path).rmIf((doc) => doc?.device_code === 'dc-1')
+ expect(readFileSync(path, 'utf8')).toBe('device_code: dc-2\n')
})
- it('round-trips a flat value through disk', async () => {
- const path = join(dir, 'config.yml')
- await writeFile(path, '')
-
- const s1 = new YamlStore(path)
- s1.setRawContent('')
- s1.doSet({ key: 'workspace', default: '' }, 'ws-123')
- writeFileSync(path, s1.getRawContent() ?? '')
-
- const s2 = new YamlStore(path)
- s2.setRawContent(readFileSync(path, 'utf8'))
- expect(s2.doGet({ key: 'workspace', default: '' })).toBe('ws-123')
- })
-
- it('round-trips a deep nested value through disk', async () => {
- const path = join(dir, 'config.yml')
- await writeFile(path, '')
-
- const s1 = new YamlStore(path)
- s1.setRawContent('')
- s1.doSet({ key: 'a.b.c', default: '' }, 'deep')
- writeFileSync(path, s1.getRawContent() ?? '')
-
- const s2 = new YamlStore(path)
- s2.setRawContent(readFileSync(path, 'utf8'))
- expect(s2.doGet({ key: 'a.b.c', default: '' })).toBe('deep')
+ it('is a no-op when the file does not exist', async () => {
+ await new YamlStore(path).rmIf(() => true)
+ expect(existsSync(path)).toBe(false)
})
+})
- it('second doSet on a reloaded store does not clobber the first key', async () => {
- const path = join(dir, 'config.yml')
- await writeFile(path, '')
-
- const s1 = new YamlStore(path)
- s1.setRawContent('')
- s1.doSet({ key: 'x', default: '' }, 'first')
- writeFileSync(path, s1.getRawContent() ?? '')
-
- const s2 = new YamlStore(path)
- s2.setRawContent(readFileSync(path, 'utf8'))
- s2.doSet({ key: 'y', default: '' }, 'second')
- writeFileSync(path, s2.getRawContent() ?? '')
-
- const s3 = new YamlStore(path)
- s3.setRawContent(readFileSync(path, 'utf8'))
- expect(s3.doGet({ key: 'x', default: '' })).toBe('first')
- expect(s3.doGet({ key: 'y', default: '' })).toBe('second')
- })
+describe('YamlStore persistence', () => {
+ it('round-trips a nested document through disk', async () => {
+ await new YamlStore(path).setTyped({ a: { b: { c: 'deep' } }, workspace: 'ws-123' })
+ expect(await new YamlStore(path).getTyped()).toEqual({
+ a: { b: { c: 'deep' } },
+ workspace: 'ws-123',
+ })
+ })
+
+ it.skipIf(process.platform === 'win32')(
+ 'writes the file with owner-only permissions',
+ async () => {
+ await new YamlStore(path).setTyped({ token: 'abc-123' })
+ expect(statSync(path).mode & 0o777).toBe(0o600)
+ },
+ )
it('forgets its cached content once the file is deleted and reloaded', async () => {
- const path = join(dir, 'config.yml')
await writeFile(path, 'key: value\n')
const store = new YamlStore(path)
@@ -265,24 +156,7 @@ describe('YamlStore persistence', () => {
expect(await store.getTyped<{ key: string }>()).toBeNull()
})
- it('load → doSet → flush writes the value to disk', async () => {
- const path = join(dir, 'config.yml')
- await writeFile(path, 'existing: value\n')
-
- const store = new YamlStore(path)
- await store.load()
- store.doSet({ key: 'token', default: '' }, 'abc-123')
- await store.flush()
-
- const raw = readFileSync(path, 'utf8')
- const store2 = new YamlStore(path)
- store2.setRawContent(raw)
- expect(store2.doGet({ key: 'token', default: '' })).toBe('abc-123')
- expect(store2.doGet({ key: 'existing', default: '' })).toBe('value')
- })
-
it('flush writes file when dirty (content changed from undefined)', async () => {
- const path = join(dir, 'config.yml')
const store = new YamlStore(path)
store.setRawContent('key: value\n')
await store.flush()
@@ -291,7 +165,6 @@ describe('YamlStore persistence', () => {
})
it('flush is a no-op when loaded content is set back unchanged', async () => {
- const path = join(dir, 'config.yml')
await writeFile(path, 'key: value\n')
const store = new YamlStore(path)
await store.load()
diff --git a/cli/src/store/store.ts b/cli/src/store/store.ts
index f692ed55474..172783d4653 100644
--- a/cli/src/store/store.ts
+++ b/cli/src/store/store.ts
@@ -2,7 +2,6 @@ import type { Options as LockOptions } from 'lockfile'
import type { Platform } from '@/sys'
import { promises as fsp } from 'node:fs'
import { dirname } from 'node:path'
-import { AsyncEntry } from '@napi-rs/keyring'
import {
binaryTag,
CORE_SCHEMA,
@@ -17,11 +16,12 @@ import {
} from 'js-yaml'
import lockfile from 'lockfile'
import { pid, resolvePlatform } from '@/sys'
+import { DIR_PERM, FILE_PERM } from './dir'
import { BadYamlFormatError, ConcurrentAccessError } from './errors'
-const FILE_PERM = 0o600
-const DIR_PERM = 0o700
const LOCK_STALE_MS = 30_000
+// Parallel difyctl runs (an agent's usual case) wait their turn instead of failing.
+const LOCK_WAIT_MS = 5_000
const YAML_LOAD_SCHEMA = CORE_SCHEMA.withTags(
binaryTag,
mergeTag,
@@ -43,21 +43,10 @@ function unlockAsync(path: string): Promise<void> {
})
}
-export type Key<T> = {
- default: T
- key: string
-}
-
-export type Store = {
- get: <T>(key: Key<T>) => Promise<T>
- set: <T>(key: Key<T>, value: T) => Promise<void>
- unset: <T>(key: Key<T>) => Promise<void>
-}
-
export const STORAGE_MODES = ['keychain', 'file'] as const
export type StorageMode = (typeof STORAGE_MODES)[number]
-abstract class FileBasedStore implements Store {
+export class YamlStore {
filePath: string
private rawContent: string | undefined
private readonly platform: Platform
@@ -110,6 +99,7 @@ abstract class FileBasedStore implements Store {
try {
await lockAsync(`${this.filePath}.lock`, {
stale: LOCK_STALE_MS,
+ wait: LOCK_WAIT_MS,
})
} catch (err) {
const code = (err as NodeJS.ErrnoException).code
@@ -142,7 +132,7 @@ abstract class FileBasedStore implements Store {
return this.rawContent
}
- protected async withLock<R>(body: () => R | Promise<R>): Promise<R> {
+ private async withLock<R>(body: () => R | Promise<R>): Promise<R> {
await this.lock()
try {
return await body()
@@ -151,29 +141,6 @@ abstract class FileBasedStore implements Store {
}
}
- async get<T>(key: Key<T>): Promise<T> {
- return this.withLock(async () => {
- await this.load()
- return this.doGet(key)
- })
- }
-
- async set<T>(key: Key<T>, value: T): Promise<void> {
- await this.withLock(async () => {
- await this.load()
- this.doSet(key, value)
- await this.flush()
- })
- }
-
- async unset<T>(key: Key<T>): Promise<void> {
- await this.withLock(async () => {
- await this.load()
- this.doUnset(key)
- await this.flush()
- })
- }
-
/**
* Remove the underlying file of the store. No-op if file doesn't exist.
*/
@@ -185,26 +152,15 @@ abstract class FileBasedStore implements Store {
}
}
- abstract doGet<T>(key: Key<T>): T
- abstract doSet<T>(key: Key<T>, value: T): void
- abstract doUnset<T>(key: Key<T>): void
-}
-
-export class YamlStore extends FileBasedStore {
- constructor(file_path: string) {
- super(file_path)
- }
-
- doGet<T>(key: Key<T>): T {
- const data = loadYaml(this.getRawContent(), this.filePath)
- const parts = key.key.split('.')
- let current: unknown = data
- for (const part of parts) {
- if (current === null || current === undefined || typeof current !== 'object')
- return key.default
- current = (current as Record<string, unknown>)[part]
- }
- return (current as T) ?? key.default
+ /**
+ * Remove the file only when `matches` accepts what it holds now. The read and the
+ * removal share one lock, so a file another process rewrote in between survives.
+ */
+ async rmIf(matches: (doc: Record<string, unknown> | null) => boolean): Promise<void> {
+ await this.withLock(async () => {
+ await this.load()
+ if (matches(loadYaml(this.getRawContent(), this.filePath))) await this.rm()
+ })
}
async getTyped<T>(): Promise<T | null> {
@@ -221,41 +177,6 @@ export class YamlStore extends FileBasedStore {
await this.flush()
})
}
-
- doSet<T>(key: Key<T>, value: T): void {
- const data = loadYaml(this.getRawContent(), this.filePath) || {}
- const parts = key.key.split('.')
- const lastKey = parts.pop()
- if (lastKey === undefined) return
- let current: Record<string, unknown> = data
- for (const part of parts) {
- if (
- current[part] === null ||
- current[part] === undefined ||
- typeof current[part] !== 'object'
- )
- current[part] = {}
- current = current[part] as Record<string, unknown>
- }
- current[lastKey] = value
- this.setRawContent(dump(data, { lineWidth: -1, noRefs: true }))
- }
-
- doUnset<T>(key: Key<T>): void {
- const data = loadYaml(this.getRawContent(), this.filePath) || {}
- const parts = key.key.split('.')
- const lastKey = parts.pop()
- if (lastKey === undefined) return
- let current: Record<string, unknown> = data
- for (const part of parts) {
- const next = current[part]
- if (next === null || next === undefined || typeof next !== 'object') return
- current = next as Record<string, unknown>
- }
- if (!(lastKey in current)) return
- delete current[lastKey]
- this.setRawContent(dump(data, { lineWidth: -1, noRefs: true }))
- }
}
function loadYaml(raw: string | undefined, file_path: string): Record<string, unknown> | null {
@@ -270,38 +191,3 @@ function loadYaml(raw: string | undefined, file_path: string): Record<string, un
throw err
}
}
-
-/**
- * OS-keyring-based storage primitive. Sits at the same layer as
- * `FileBasedStore`: implements `Store` with each `Key<T>` corresponding to a
- * single keyring entry under the configured service. Values are JSON-encoded.
- */
-export class KeyringBasedStore implements Store {
- private readonly service: string
-
- constructor(service: string) {
- this.service = service
- }
-
- async get<T>(key: Key<T>): Promise<T> {
- try {
- const v = await new AsyncEntry(this.service, key.key).getPassword()
- if (v === null || v === undefined || v === '') return key.default
- return JSON.parse(v) as T
- } catch {
- return key.default
- }
- }
-
- async set<T>(key: Key<T>, value: T): Promise<void> {
- await new AsyncEntry(this.service, key.key).setPassword(JSON.stringify(value))
- }
-
- async unset<T>(key: Key<T>): Promise<void> {
- try {
- await new AsyncEntry(this.service, key.key).deletePassword()
- } catch {
- /* missing entry is fine */
- }
- }
-}
diff --git a/cli/src/store/token-store.test.ts b/cli/src/store/token-store.test.ts
index eb609c6929e..6efd2ed0dc6 100644
--- a/cli/src/store/token-store.test.ts
+++ b/cli/src/store/token-store.test.ts
@@ -1,32 +1,45 @@
+import type { BufferStreams } from '@/sys/io/streams'
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it } from 'vite-plus/test'
-import { FileTokenStore } from './token-store'
+import { ioService } from '@/plugins/io'
+import { TOKENS_FILE_NAME } from '@/plugins/token'
+import { bufferStreams } from '@/sys/io/streams'
+import { localFile } from './local-file'
+import { FileTokenStore, TOKENS_SCHEMA } from './token-store'
describe('FileTokenStore', () => {
let dir: string
let file: string
+ let streams: BufferStreams
beforeEach(() => {
+ streams = bufferStreams()
dir = mkdtempSync(join(tmpdir(), 'difyctl-tok-'))
- file = join(dir, 'tokens.yml')
+ file = join(dir, TOKENS_FILE_NAME)
})
- afterEach(() => rmSync(dir, { recursive: true, force: true }))
+ afterEach(() => {
+ rmSync(dir, { recursive: true, force: true })
+ })
+
+ function open(): FileTokenStore {
+ return new FileTokenStore(localFile(file, TOKENS_SCHEMA, ioService(streams).notice))
+ }
it('returns empty string for a missing credential', async () => {
- const s = new FileTokenStore(file)
+ const s = open()
expect(await s.read('https://cloud.dify.ai', '[email protected]')).toBe('')
})
it('round-trips a bearer with dots and @ kept literal', async () => {
- const s = new FileTokenStore(file)
+ const s = open()
await s.write('https://cloud.dify.ai', '[email protected]', 'dfoa_secret')
expect(await s.read('https://cloud.dify.ai', '[email protected]')).toBe('dfoa_secret')
})
it('keeps multiple accounts under one host and isolates hosts', async () => {
- const s = new FileTokenStore(file)
+ const s = open()
await s.write('https://cloud.dify.ai', '[email protected]', 'A')
await s.write('https://cloud.dify.ai', '[email protected]', 'B')
await s.write('https://self.example.com', '[email protected]', 'C')
@@ -35,38 +48,53 @@ describe('FileTokenStore', () => {
expect(await s.read('https://self.example.com', '[email protected]')).toBe('C')
})
- it('persists the versioned nested shape on disk', async () => {
- const s = new FileTokenStore(file)
+ it('persists the nested shape on disk', async () => {
+ const s = open()
await s.write('https://cloud.dify.ai', '[email protected]', 'A')
- const raw = readFileSync(file, 'utf8')
- expect(raw).toContain('version: 1')
- expect(raw).toContain('https://cloud.dify.ai')
- expect(raw).toContain('[email protected]')
+ expect(readFileSync(file, 'utf8')).toBe('tokens:\n https://cloud.dify.ai:\n [email protected]: A\n')
})
- it('reads empty when the document version is an unknown future version', async () => {
- writeFileSync(file, 'version: 999\ntokens:\n "h":\n "e": "x"\n')
- const s = new FileTokenStore(file)
- expect(await s.read('h', 'e')).toBe('')
+ it('reads a difyctl v1 file in place and drops its version on the next write', async () => {
+ writeFileSync(file, 'version: 1\ntokens:\n h:\n e: dfoa_v1\n')
+ const s = open()
+ expect(await s.read('h', 'e')).toBe('dfoa_v1')
+ await s.write('h', 'f', 'dfoa_v2')
+ expect(readFileSync(file, 'utf8')).toBe('tokens:\n h:\n e: dfoa_v1\n f: dfoa_v2\n')
+ expect(streams.errBuf()).toBe('')
})
- it('reads tokens from legacy format (no version field) for transparent migration', async () => {
- writeFileSync(file, 'tokens:\n "h":\n "e": "dfoa_legacy"\n')
- const s = new FileTokenStore(file)
- expect(await s.read('h', 'e')).toBe('dfoa_legacy')
+ it('ignores unknown and future keys without a notice', async () => {
+ writeFileSync(file, 'schema_version: 99\nfuture_key: x\ntokens:\n h:\n e: dfoa_x\n')
+ expect(await open().read('h', 'e')).toBe('dfoa_x')
+ expect(streams.errBuf()).toBe('')
})
- it('preserves existing tokens and stamps version when writing to a legacy file', async () => {
- writeFileSync(file, 'tokens:\n "h":\n "existing@x": "dfoa_existing"\n')
- const s = new FileTokenStore(file)
- await s.write('h', 'new@x', 'dfoa_new')
- expect(await s.read('h', 'existing@x')).toBe('dfoa_existing')
- expect(await s.read('h', 'new@x')).toBe('dfoa_new')
- expect(readFileSync(file, 'utf8')).toContain('version: 1')
+ it('drops a bad entry with a notice and keeps the rest', async () => {
+ writeFileSync(file, 'tokens:\n h:\n e: dfoa_x\n bad: 7\n g: nope\n')
+ const s = open()
+ expect(await s.read('h', 'e')).toBe('dfoa_x')
+ expect(streams.errBuf()).toBe(
+ `${file}: ignoring the invalid value of tokens.h.bad\n${file}: ignoring the invalid value of tokens.g\n`,
+ )
})
+ it.each([
+ ['not valid YAML', 'tokens: [unclosed\n', /is not valid YAML/],
+ ['not a mapping', 'just text\n', /is not a YAML mapping/],
+ ])(
+ 'reads a file that is %s as empty and replaces it on the next write',
+ async (_l, raw, note) => {
+ writeFileSync(file, raw)
+ const s = open()
+ expect(await s.read('h', 'e')).toBe('')
+ expect(streams.errBuf()).toMatch(note)
+ await s.write('h', 'e', 'dfoa_y')
+ expect(readFileSync(file, 'utf8')).toBe('tokens:\n h:\n e: dfoa_y\n')
+ },
+ )
+
it('remove deletes the credential and prunes the empty host map', async () => {
- const s = new FileTokenStore(file)
+ const s = open()
await s.write('https://cloud.dify.ai', '[email protected]', 'A')
await s.remove('https://cloud.dify.ai', '[email protected]')
expect(await s.read('https://cloud.dify.ai', '[email protected]')).toBe('')
@@ -75,7 +103,7 @@ describe('FileTokenStore', () => {
})
it('remove is a no-op for an absent credential', async () => {
- const s = new FileTokenStore(file)
+ const s = open()
await expect(s.remove('h', 'e')).resolves.not.toThrow()
})
})
diff --git a/cli/src/store/token-store.ts b/cli/src/store/token-store.ts
index 1dc4d643b89..2728a02e895 100644
--- a/cli/src/store/token-store.ts
+++ b/cli/src/store/token-store.ts
@@ -1,7 +1,9 @@
+import type { LocalFile } from './local-file'
import { AsyncEntry } from '@napi-rs/keyring'
+import { z } from 'zod'
import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
-import { YamlStore } from './store'
+import { BINARY } from '@/version/info'
/**
* Credential store keyed by an opaque (host, email) pair.
@@ -12,60 +14,40 @@ export type TokenStore = {
remove: (host: string, email: string) => Promise<void>
}
-const DOC_VERSION = 1
+const KEYCHAIN_ENTRY_PREFIX = 'tokens'
-export type TokenDoc = {
- version?: number
- tokens?: Record<string, Record<string, string>>
-}
+export const TOKENS_SCHEMA = z.object({
+ tokens: z.record(z.string(), z.record(z.string(), z.string())).default({}),
+})
+
+type TokensDoc = z.infer<typeof TOKENS_SCHEMA>
+
+export type TokensFile = LocalFile<TokensDoc>
export class FileTokenStore implements TokenStore {
- private readonly store: YamlStore
+ private readonly file: TokensFile
- constructor(filePath: string) {
- this.store = new YamlStore(filePath)
+ constructor(file: TokensFile) {
+ this.file = file
}
async read(host: string, email: string): Promise<string> {
- const doc = await this.store.getTyped<TokenDoc>()
- if (doc === null) return ''
- // missing version = legacy pre-v1 format (same data shape); future unknown versions are rejected
- if (doc.version !== undefined && doc.version !== DOC_VERSION) return ''
- return doc.tokens?.[host]?.[email] ?? ''
+ return (await this.file.read())?.tokens[host]?.[email] ?? ''
}
async write(host: string, email: string, bearer: string): Promise<void> {
- const doc = await this.load()
- const hostMap = doc.tokens[host] ?? {}
- hostMap[email] = bearer
- doc.tokens[host] = hostMap
- await this.store.setTyped(doc)
+ const doc = (await this.file.read()) ?? { tokens: {} }
+ doc.tokens[host] = { ...doc.tokens[host], [email]: bearer }
+ await this.file.write(doc)
}
async remove(host: string, email: string): Promise<void> {
- const doc = await this.store.getTyped<TokenDoc>()
- if (doc === null) return
- if (doc.version !== undefined && doc.version !== DOC_VERSION) return
- const tokens = doc.tokens ?? {}
- const hostMap = tokens[host]
- if (hostMap === undefined || !(email in hostMap)) return
+ const doc = await this.file.read()
+ const hostMap = doc?.tokens[host]
+ if (doc === null || hostMap === undefined || !(email in hostMap)) return
delete hostMap[email]
- if (Object.keys(hostMap).length === 0) delete tokens[host]
- await this.store.setTyped({ version: DOC_VERSION, tokens })
- }
-
- private async load(): Promise<{
- version: number
- tokens: Record<string, Record<string, string>>
- }> {
- const doc = await this.store.getTyped<TokenDoc>()
- if (doc === null) return { version: DOC_VERSION, tokens: {} }
- if (doc.version !== undefined && doc.version !== DOC_VERSION)
- return { version: DOC_VERSION, tokens: {} }
- return {
- version: DOC_VERSION,
- tokens: (doc.tokens ?? {}) as Record<string, Record<string, string>>,
- }
+ if (Object.keys(hostMap).length === 0) delete doc.tokens[host]
+ await this.file.write(doc)
}
}
@@ -82,7 +64,7 @@ export class KeychainTokenStore implements TokenStore {
async read(host: string, email: string): Promise<string> {
let raw: string | null | undefined
try {
- raw = await new AsyncEntry(this.service, entryName(host, email)).getPassword()
+ raw = await new AsyncEntry(this.service, this.entry(host, email)).getPassword()
} catch (err) {
throw keyringUnavailableError(err)
}
@@ -97,7 +79,9 @@ export class KeychainTokenStore implements TokenStore {
async write(host: string, email: string, bearer: string): Promise<void> {
try {
- await new AsyncEntry(this.service, entryName(host, email)).setPassword(JSON.stringify(bearer))
+ await new AsyncEntry(this.service, this.entry(host, email)).setPassword(
+ JSON.stringify(bearer),
+ )
} catch (err) {
throw keyringUnavailableError(err)
}
@@ -105,22 +89,22 @@ export class KeychainTokenStore implements TokenStore {
async remove(host: string, email: string): Promise<void> {
try {
- await new AsyncEntry(this.service, entryName(host, email)).deletePassword()
+ await new AsyncEntry(this.service, this.entry(host, email)).deletePassword()
} catch {
/* missing entry is fine */
}
}
-}
-function entryName(host: string, email: string): string {
- return `tokens.${host}.${email}`
+ private entry(host: string, email: string): string {
+ return `${KEYCHAIN_ENTRY_PREFIX}.${host}.${email}`
+ }
}
function keyringUnavailableError(cause: unknown): BaseError {
return new BaseError({
code: ErrorCode.KeyringUnavailable,
message: 'OS keychain is unreachable',
- hint: 'credentials are stored in the system keychain but it could not be accessed; unlock the keychain (or the login session) and retry',
+ hint: `unlock the keychain (or the login session) and retry, or run ${BINARY} login --server <url> --no-keyring to keep the token in a file`,
cause,
})
}
diff --git a/cli/src/sys/index.test.ts b/cli/src/sys/index.test.ts
index 95208d63fe7..485eb5f316d 100644
--- a/cli/src/sys/index.test.ts
+++ b/cli/src/sys/index.test.ts
@@ -18,17 +18,6 @@ describe('resolvePlatform', () => {
}
})
- it('cacheDir ends with the difyctl subdir', () => {
- const p = resolvePlatform()
- if (p.id() === 'win32') {
- expect(p.cacheDir()).toMatch(/difyctl$/)
- } else if (p.id() === 'darwin') {
- expect(p.cacheDir()).toBe(join(homedir(), 'Library', 'Caches', SUBDIR))
- } else {
- expect(p.cacheDir()).toBe(join(homedir(), '.cache', SUBDIR))
- }
- })
-
it('atomicReplace is a function', () => {
expect(resolvePlatform().atomicReplace).toBeTypeOf('function')
})
diff --git a/cli/src/sys/index.ts b/cli/src/sys/index.ts
index 513a86fd4bf..e4af246ebac 100644
--- a/cli/src/sys/index.ts
+++ b/cli/src/sys/index.ts
@@ -6,6 +6,18 @@ export function getEnv(name: string): string | undefined {
return process.env[name]
}
+export type EmbeddedFile = Blob & { readonly name: string }
+
+type BunGlobal = { embeddedFiles?: readonly EmbeddedFile[] }
+
+export function embeddedFiles(): readonly EmbeddedFile[] {
+ return (globalThis as { Bun?: BunGlobal }).Bun?.embeddedFiles ?? []
+}
+
+export function isCompiledBinary(): boolean {
+ return __DIFYCTL_COMPILED__
+}
+
export function env(): NodeJS.ProcessEnv {
return process.env
}
@@ -51,16 +63,22 @@ export function pid(): number {
export type Platform = {
id: () => NodeJS.Platform
configDir: () => string
- cacheDir: () => string
atomicReplace: (src: string, dst: string) => void
}
export const SUBDIR = 'difyctl'
export const ENV_XDG_CONFIG_HOME = 'XDG_CONFIG_HOME'
-export const ENV_XDG_CACHE_HOME = 'XDG_CACHE_HOME'
-function appDataDir(): string | undefined {
- return getEnv('APPDATA') ?? getEnv('LOCALAPPDATA')
+const APP_DATA_VARS = ['APPDATA', 'LOCALAPPDATA'] as const
+
+// The first of these that is set.
+function appDataDir(): string {
+ const dir = APP_DATA_VARS.map(getEnv).find((value) => value !== undefined && value !== '')
+ if (dir === undefined)
+ throw new Error(
+ `cannot resolve ${APP_DATA_VARS.map((name) => `%${name}%`).join(' or ')} on Windows`,
+ )
+ return join(dir, SUBDIR)
}
type PlatformFactory = () => Platform
@@ -82,32 +100,16 @@ const platformImpls: Partial<Record<NodeJS.Platform, PlatformFactory>> = {
? join(xdg, SUBDIR)
: join(homedir(), '.config', SUBDIR)
},
- cacheDir: () => {
- const xdg = getEnv(ENV_XDG_CACHE_HOME)
- return xdg !== undefined && xdg !== '' ? join(xdg, SUBDIR) : join(homedir(), '.cache', SUBDIR)
- },
atomicReplace: posixAtomicReplace,
}),
darwin: () => ({
id: () => 'darwin',
configDir: () => join(homedir(), '.config', SUBDIR),
- cacheDir: () => join(homedir(), 'Library', 'Caches', SUBDIR),
atomicReplace: posixAtomicReplace,
}),
win32: () => ({
id: () => 'win32',
- configDir: () => {
- const appData = appDataDir()
- if (appData === undefined || appData === '')
- throw new Error('cannot resolve %APPDATA% on Windows')
- return join(appData, SUBDIR)
- },
- cacheDir: () => {
- const appData = appDataDir()
- if (appData === undefined || appData === '')
- throw new Error('cannot resolve %LOCALAPPDATA% on Windows')
- return join(appData, SUBDIR)
- },
+ configDir: appDataDir,
atomicReplace: win32AtomicReplace,
}),
}
@@ -115,7 +117,6 @@ const platformImpls: Partial<Record<NodeJS.Platform, PlatformFactory>> = {
const defaultPlatformFactory: PlatformFactory = () => ({
id: () => platform(),
configDir: () => join(homedir(), '.config', SUBDIR),
- cacheDir: () => join(homedir(), '.cache', SUBDIR),
atomicReplace: posixAtomicReplace,
})
diff --git a/cli/src/util/flag-name.ts b/cli/src/util/flag-name.ts
index f398273298d..73d7eb7efae 100644
--- a/cli/src/util/flag-name.ts
+++ b/cli/src/util/flag-name.ts
@@ -1,5 +1,8 @@
const FLAG_WORD_SEPARATOR = '-'
const PROPERTY_WORD_SEPARATOR = '_'
+const FLAG_PREFIX = '--'
+const ARG_OPEN = '<'
+const ARG_CLOSE = '>'
/** The name a typed word stands for: dashes are an alias for the underscores ids use. */
export function propertyFor(name: string): string {
@@ -10,3 +13,15 @@ export function propertyFor(name: string): string {
export function flagFor(name: string): string {
return name.split(PROPERTY_WORD_SEPARATOR).join(FLAG_WORD_SEPARATOR)
}
+
+export function flagToken(name: string): string {
+ return `${FLAG_PREFIX}${flagFor(name)}`
+}
+
+export function argToken(name: string): string {
+ return `${ARG_OPEN}${name}${ARG_CLOSE}`
+}
+
+export function typedName(name: string, positional: readonly string[]): string {
+ return positional.includes(name) ? argToken(name) : flagToken(name)
+}
diff --git a/cli/src/util/host.ts b/cli/src/util/host.ts
index 6d8a35a8ed9..48881070cc1 100644
--- a/cli/src/util/host.ts
+++ b/cli/src/util/host.ts
@@ -1,8 +1,6 @@
import { BaseError } from '@/errors/base'
import { ErrorCode } from '@/errors/codes'
-export const DEFAULT_HOST = 'https://cloud.dify.ai'
-
export function openAPIBase(host: string): string {
return `${host.replace(/\/+$/, '')}/openapi/v1/`
}
@@ -14,7 +12,6 @@ export type ResolveHostOptions = {
export function resolveHost(opts: ResolveHostOptions): string {
let raw = opts.raw.trim()
- if (raw === '') raw = DEFAULT_HOST
if (!raw.includes('://')) raw = `https://${raw}`
let url: URL
try {
diff --git a/cli/src/util/shell-word.ts b/cli/src/util/shell-word.ts
new file mode 100644
index 00000000000..c4a919de44d
--- /dev/null
+++ b/cli/src/util/shell-word.ts
@@ -0,0 +1,8 @@
+const SHELL_SAFE = /^[\w@%+=:,./~-]+$/
+const QUOTE = "'"
+const ESCAPED_QUOTE = `'\\''`
+
+export function shellWord(text: string): string {
+ if (SHELL_SAFE.test(text)) return text
+ return `${QUOTE}${text.split(QUOTE).join(ESCAPED_QUOTE)}${QUOTE}`
+}
diff --git a/cli/src/version/build-info.d.ts b/cli/src/version/build-info.d.ts
index 886954c0dfc..c28d3e60668 100644
--- a/cli/src/version/build-info.d.ts
+++ b/cli/src/version/build-info.d.ts
@@ -4,3 +4,4 @@ declare const __DIFYCTL_VERSION__: string
declare const __DIFYCTL_COMMIT__: string
declare const __DIFYCTL_BUILD_DATE__: string
declare const __DIFYCTL_CHANNEL__: string
+declare const __DIFYCTL_COMPILED__: boolean
diff --git a/cli/test/e2e/helpers/cli.ts b/cli/test/e2e/helpers/cli.ts
index a744ab1e451..25edce9e9ec 100644
--- a/cli/test/e2e/helpers/cli.ts
+++ b/cli/test/e2e/helpers/cli.ts
@@ -8,7 +8,6 @@
* withTempConfig) to prevent session state leaking between tests.
*/
-import type { TokenDoc } from '@/store/token-store'
import { Buffer } from 'node:buffer'
import { execSync, spawn } from 'node:child_process'
import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
@@ -203,6 +202,11 @@ function splitHost(host: string): { bare: string; scheme: string } {
return { bare, scheme }
}
+type TokenDoc = {
+ version: number
+ tokens: Record<string, Record<string, string>>
+}
+
async function writeFileToken(
configDir: string,
host: string,
@@ -291,8 +295,7 @@ export async function injectAuth(configDir: string, opts: AuthInjectionOptions):
const account = `tokens.${bare}.${email}`
new Entry('difyctl', account).setPassword(JSON.stringify(opts.bearer))
} else {
- // Fall back to tokens.yml — FileTokenStore uses getTyped<TokenDoc>()
- // which expects flat tokens[host][email] with version: 1.
+ // Fall back to tokens.yml, which FileTokenStore reads as tokens[host][email].
await writeFileToken(configDir, bare, email, opts.bearer)
}
}
diff --git a/cli/test/fixtures/catalog-v2.json b/cli/test/fixtures/catalog-v2.json
index 80815ea680b..613cc038677 100644
--- a/cli/test/fixtures/catalog-v2.json
+++ b/cli/test/fixtures/catalog-v2.json
@@ -92,6 +92,33 @@
"workspace_id": "body"
},
"deprecated": false,
+ "examples": [
+ {
+ "input": {
+ "app_id": "<app_id>",
+ "query": "Summarise the latest release"
+ },
+ "title": "Start a new conversation"
+ },
+ {
+ "input": {
+ "app_id": "<app_id>",
+ "conversation_id": "<conversation_id>",
+ "query": "Make it shorter"
+ },
+ "title": "Reply in an existing conversation"
+ },
+ {
+ "input": {
+ "app_id": "<app_id>",
+ "files": {
+ "document": "./report.pdf"
+ },
+ "query": "Summarise the document"
+ },
+ "title": "Fill a file variable with a local file"
+ }
+ ],
"input": {
"properties": {
"app_id": {
@@ -111,7 +138,7 @@
}
],
"default": null,
- "description": "Local files attached to the run itself (the app's `sys.files`), not to a variable",
+ "description": "Local file paths attached to the run itself (the app's `sys.files`), not to a variable",
"title": "Attachments"
},
"auto_generate_name": {
@@ -158,12 +185,12 @@
}
],
"default": null,
- "description": "Local files keyed by the app's file variable name; the server uploads each one and sets `inputs[<name>]`. Send a list (part name `files[<name>][]`) for a file-list variable",
+ "description": "Local file paths keyed by the app's file variable name; each file is uploaded and becomes that variable's value. Give a list of paths for a file-list variable",
"title": "Files"
},
"inputs": {
"additionalProperties": true,
- "description": "Variables declared by the app. The exact shape is per app: read `input_schema` from describe.console_app. A file variable takes a Dify file mapping (remote url or upload id) here, or a local file in `files`, not both.",
+ "description": "Variables declared by the app. The exact shape is per app: read `input_schema` from describe.console_app. A file variable takes a Dify file mapping (remote url or upload id) here, or a local path in `files`, not both.",
"title": "Inputs",
"type": "object"
},
@@ -199,7 +226,7 @@
"title": "Workspace Id"
}
},
- "required": ["app_id", "inputs", "query"],
+ "required": ["app_id", "query"],
"type": "object"
},
"internal": false,
@@ -510,6 +537,7 @@
"bind": {
"app_id": "body",
"description": "body",
+ "draft_hash": "body",
"icon": "body",
"icon_background": "body",
"icon_type": "body",
@@ -520,6 +548,30 @@
"yaml_url": "body"
},
"deprecated": false,
+ "examples": [
+ {
+ "input": {
+ "mode": "yaml-content",
+ "yaml_content": "<yaml text of the app DSL>"
+ },
+ "title": "Import an app from inline YAML"
+ },
+ {
+ "input": {
+ "mode": "yaml-url",
+ "yaml_url": "https://example.com/apps/release-summary.yml"
+ },
+ "title": "Import an app from a URL"
+ },
+ {
+ "input": {
+ "app_id": "<app_id>",
+ "mode": "yaml-content",
+ "yaml_content": "<yaml text of the app DSL>"
+ },
+ "title": "Overwrite an existing workflow app from YAML"
+ }
+ ],
"input": {
"properties": {
"app_id": {
@@ -548,6 +600,19 @@
"description": "Override the app description from the DSL",
"title": "Description"
},
+ "draft_hash": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "draft_hash from the export or restore this import is based on. The import fails if the draft's graph, features, environment variables or conversation variables changed since. Requires app_id",
+ "title": "Draft Hash"
+ },
"icon": {
"anyOf": [
{
diff --git a/cli/test/fixtures/catalog.json b/cli/test/fixtures/catalog.json
index e9c7b838d90..8677f45da3c 100644
--- a/cli/test/fixtures/catalog.json
+++ b/cli/test/fixtures/catalog.json
@@ -57,6 +57,20 @@
"path": "/openapi/v1/account/sessions/self",
"summary": "Revoke the session behind this token"
},
+ "restore.console_app.version": {
+ "bind": { "app_id": "path", "version_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "app_id": {}, "version_id": {} },
+ "required": ["app_id", "version_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/apps/{app_id}/versions/{version_id}:restore",
+ "summary": "Copy a published version into the draft; publish again to make it live"
+ },
"run.console_app.advanced_chat": {
"bind": {
"app_id": "path",
@@ -70,6 +84,28 @@
"workspace_id": "body"
},
"deprecated": false,
+ "examples": [
+ {
+ "input": { "app_id": "<app_id>", "query": "Summarise the latest release" },
+ "title": "Start a new conversation"
+ },
+ {
+ "input": {
+ "app_id": "<app_id>",
+ "conversation_id": "<conversation_id>",
+ "query": "Make it shorter"
+ },
+ "title": "Reply in an existing conversation"
+ },
+ {
+ "input": {
+ "app_id": "<app_id>",
+ "files": { "document": "./report.pdf" },
+ "query": "Summarise the document"
+ },
+ "title": "Fill a file variable with a local file"
+ }
+ ],
"input": {
"properties": {
"app_id": { "type": "string" },
@@ -79,7 +115,7 @@
{ "type": "null" }
],
"default": null,
- "description": "Local files attached to the run itself (the app's `sys.files`), not to a variable",
+ "description": "Local file paths attached to the run itself (the app's `sys.files`), not to a variable",
"title": "Attachments"
},
"auto_generate_name": {
@@ -108,12 +144,12 @@
{ "type": "null" }
],
"default": null,
- "description": "Local files keyed by the app's file variable name; the server uploads each one and sets `inputs[<name>]`. Send a list (part name `files[<name>][]`) for a file-list variable",
+ "description": "Local file paths keyed by the app's file variable name; each file is uploaded and becomes that variable's value. Give a list of paths for a file-list variable",
"title": "Files"
},
"inputs": {
"additionalProperties": true,
- "description": "Variables declared by the app. The exact shape is per app: read `input_schema` from describe.console_app. A file variable takes a Dify file mapping (remote url or upload id) here, or a local file in `files`, not both.",
+ "description": "Variables declared by the app. The exact shape is per app: read `input_schema` from describe.console_app. A file variable takes a Dify file mapping (remote url or upload id) here, or a local path in `files`, not both.",
"title": "Inputs",
"type": "object"
},
@@ -131,7 +167,7 @@
"title": "Workspace Id"
}
},
- "required": ["app_id", "inputs", "query"],
+ "required": ["app_id", "query"],
"type": "object"
},
"internal": false,
@@ -346,6 +382,7 @@
"bind": {
"app_id": "body",
"description": "body",
+ "draft_hash": "body",
"icon": "body",
"icon_background": "body",
"icon_type": "body",
@@ -356,6 +393,27 @@
"yaml_url": "body"
},
"deprecated": false,
+ "examples": [
+ {
+ "input": { "mode": "yaml-content", "yaml_content": "<yaml text of the app DSL>" },
+ "title": "Import an app from inline YAML"
+ },
+ {
+ "input": {
+ "mode": "yaml-url",
+ "yaml_url": "https://example.com/apps/release-summary.yml"
+ },
+ "title": "Import an app from a URL"
+ },
+ {
+ "input": {
+ "app_id": "<app_id>",
+ "mode": "yaml-content",
+ "yaml_content": "<yaml text of the app DSL>"
+ },
+ "title": "Overwrite an existing workflow app from YAML"
+ }
+ ],
"input": {
"properties": {
"app_id": {
@@ -370,6 +428,12 @@
"description": "Override the app description from the DSL",
"title": "Description"
},
+ "draft_hash": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "default": null,
+ "description": "draft_hash from the export or restore this import is based on. The import fails if the draft's graph, features, environment variables or conversation variables changed since. Requires app_id",
+ "title": "Draft Hash"
+ },
"icon": {
"anyOf": [{ "type": "string" }, { "type": "null" }],
"default": null,
@@ -917,6 +981,846 @@
"method": "POST",
"path": "/openapi/v1/workspaces/{workspace_id}:switch",
"summary": "Server-side current switch workspace (shared with the web console)"
+ },
+ "create.console_app.workflow": {
+ "bind": {
+ "description": "body",
+ "icon": "body",
+ "icon_background": "body",
+ "icon_type": "body",
+ "name": "body",
+ "workspace_id": "path"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "description": {},
+ "icon": {},
+ "icon_background": {},
+ "icon_type": {},
+ "name": {},
+ "workspace_id": {}
+ },
+ "required": ["workspace_id", "name"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/workspaces/{workspace_id}/apps/workflow",
+ "summary": "Create a blank workflow app; export its DSL to start building"
+ },
+ "create.console_app.advanced_chat": {
+ "bind": {
+ "description": "body",
+ "icon": "body",
+ "icon_background": "body",
+ "icon_type": "body",
+ "name": "body",
+ "workspace_id": "path"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "description": {},
+ "icon": {},
+ "icon_background": {},
+ "icon_type": {},
+ "name": {},
+ "workspace_id": {}
+ },
+ "required": ["workspace_id", "name"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/workspaces/{workspace_id}/apps/advanced-chat",
+ "summary": "Create a blank advanced-chat app; export its DSL to start building"
+ },
+ "test.node.workflow": {
+ "bind": { "app_id": "path", "files": "body", "inputs": "body", "node_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "app_id": {}, "files": {}, "inputs": {}, "node_id": {} },
+ "required": ["app_id", "node_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/apps/{app_id}/draft/workflow/nodes/{node_id}:run",
+ "summary": "Test one node of a workflow draft, reusing what the last draft run saved"
+ },
+ "test.node.advanced_chat": {
+ "bind": {
+ "app_id": "path",
+ "files": "body",
+ "inputs": "body",
+ "node_id": "path",
+ "query": "body"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "app_id": {}, "files": {}, "inputs": {}, "node_id": {}, "query": {} },
+ "required": ["app_id", "node_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/apps/{app_id}/draft/advanced-chat/nodes/{node_id}:run",
+ "summary": "Test one node of an advanced-chat draft, reusing what the last draft run saved"
+ },
+ "test.console_app.workflow": {
+ "bind": {
+ "app_id": "path",
+ "attachments": "file",
+ "files": "file",
+ "inputs": "body",
+ "workspace_id": "body"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "app_id": {},
+ "attachments": {},
+ "files": {},
+ "inputs": {},
+ "workspace_id": {}
+ },
+ "required": ["app_id"]
+ },
+ "internal": false,
+ "kind": "sse",
+ "method": "POST",
+ "path": "/openapi/v1/apps/{app_id}/draft/workflow:run",
+ "summary": "Test-run the draft of a workflow app; streams workflow events. A human-input pause in a draft run cannot be resumed over openapi."
+ },
+ "test.console_app.advanced_chat": {
+ "bind": {
+ "app_id": "path",
+ "attachments": "file",
+ "auto_generate_name": "body",
+ "conversation_id": "body",
+ "files": "file",
+ "inputs": "body",
+ "query": "body",
+ "workspace_id": "body"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "app_id": {},
+ "attachments": {},
+ "auto_generate_name": {},
+ "conversation_id": {},
+ "files": {},
+ "inputs": {},
+ "query": {},
+ "workspace_id": {}
+ },
+ "required": ["app_id", "query"]
+ },
+ "internal": false,
+ "kind": "sse",
+ "method": "POST",
+ "path": "/openapi/v1/apps/{app_id}/draft/advanced-chat:run",
+ "summary": "Test-run the draft of an advanced-chat app; streams message and workflow events. A human-input pause in a draft run cannot be resumed over openapi."
+ },
+ "check.console_app.dsl": {
+ "bind": { "app_id": "body", "workspace_id": "path", "yaml_content": "body" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "app_id": {}, "workspace_id": {}, "yaml_content": {} },
+ "required": ["workspace_id", "yaml_content"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/workspaces/{workspace_id}/apps/imports:check",
+ "summary": "Check app DSL and list every problem"
+ },
+ "check.console_app.release": {
+ "bind": { "app_id": "path" },
+ "deprecated": false,
+ "input": { "type": "object", "properties": { "app_id": {} }, "required": ["app_id"] },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/apps/{app_id}/release:check",
+ "summary": "Check whether an app draft is ready to publish and what changed"
+ },
+ "get.knowledge_base": {
+ "bind": { "limit": "query", "page": "query", "query": "query", "workspace_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "limit": {}, "page": {}, "query": {}, "workspace_id": {} },
+ "required": ["workspace_id"]
+ },
+ "internal": false,
+ "kind": "list",
+ "method": "GET",
+ "path": "/openapi/v1/workspaces/{workspace_id}/knowledge-bases",
+ "summary": "List knowledge bases"
+ },
+ "describe.service_api": {
+ "bind": { "app_id": "path" },
+ "deprecated": false,
+ "input": { "type": "object", "properties": { "app_id": {} }, "required": ["app_id"] },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/apps/{app_id}/service-api",
+ "summary": "Show an app's Service API settings"
+ },
+ "set.service_api": {
+ "bind": { "app_id": "path", "enabled": "body" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "app_id": {}, "enabled": {} },
+ "required": ["app_id", "enabled"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "PATCH",
+ "path": "/openapi/v1/apps/{app_id}/service-api",
+ "summary": "Turn an app's Service API on or off"
+ },
+ "describe.webapp_access": {
+ "bind": { "app_id": "path" },
+ "deprecated": false,
+ "input": { "type": "object", "properties": { "app_id": {} }, "required": ["app_id"] },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/apps/{app_id}/webapp-access",
+ "summary": "Show who can open an app's web app"
+ },
+ "set.webapp_access": {
+ "bind": { "access_mode": "body", "app_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "access_mode": {}, "app_id": {} },
+ "required": ["app_id", "access_mode"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "PUT",
+ "path": "/openapi/v1/apps/{app_id}/webapp-access",
+ "summary": "Set who can open an app's web app"
+ },
+ "reset.webapp": {
+ "bind": { "app_id": "path" },
+ "deprecated": false,
+ "input": { "type": "object", "properties": { "app_id": {} }, "required": ["app_id"] },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/apps/{app_id}/webapp:reset",
+ "summary": "Reset an app's web app address"
+ },
+ "get.node_type": {
+ "bind": {},
+ "deprecated": false,
+ "input": { "type": "object", "properties": {} },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/node-types",
+ "summary": "Every node type this server can run; import decides which a mode allows"
+ },
+ "describe.node_type": {
+ "bind": { "node_type": "path" },
+ "deprecated": false,
+ "input": { "type": "object", "properties": { "node_type": {} }, "required": ["node_type"] },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/node-types/{node_type}",
+ "summary": "The JSON schema of a node type's data and its default config"
+ },
+ "get.run": {
+ "bind": {
+ "app_id": "path",
+ "last_id": "query",
+ "limit": "query",
+ "status": "query",
+ "triggered_from": "query"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "app_id": {},
+ "last_id": {},
+ "limit": {},
+ "status": {},
+ "triggered_from": {}
+ },
+ "required": ["app_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/apps/{app_id}/runs",
+ "summary": "List runs of a workflow or advanced-chat app, newest first"
+ },
+ "get.run.node": {
+ "bind": { "app_id": "path", "run_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "app_id": {}, "run_id": {} },
+ "required": ["app_id", "run_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/apps/{app_id}/runs/{run_id}/nodes",
+ "summary": "Each node step of a run, to find the one that failed"
+ },
+ "publish.console_app": {
+ "bind": { "app_id": "path", "marked_comment": "body", "marked_name": "body" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "app_id": {}, "marked_comment": {}, "marked_name": {} },
+ "required": ["app_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/apps/{app_id}:publish",
+ "summary": "Publish the draft as a new version and make the app use it"
+ },
+ "get.console_app.version": {
+ "bind": { "app_id": "path", "limit": "query", "named_only": "query", "page": "query" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "app_id": {}, "limit": {}, "named_only": {}, "page": {} },
+ "required": ["app_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/apps/{app_id}/versions",
+ "summary": "List published versions, newest first"
+ },
+ "set.webapp.workflow": {
+ "bind": {
+ "app_id": "path",
+ "copyright": "body",
+ "custom_disclaimer": "body",
+ "default_language": "body",
+ "description": "body",
+ "enabled": "body",
+ "icon": "body",
+ "icon_background": "body",
+ "icon_type": "body",
+ "privacy_policy": "body",
+ "show_workflow_steps": "body",
+ "title": "body"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "app_id": {},
+ "copyright": {},
+ "custom_disclaimer": {},
+ "default_language": {},
+ "description": {},
+ "enabled": {},
+ "icon": {},
+ "icon_background": {},
+ "icon_type": {},
+ "privacy_policy": {},
+ "show_workflow_steps": {},
+ "title": {}
+ },
+ "required": ["app_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "PATCH",
+ "path": "/openapi/v1/apps/{app_id}/webapp/workflow",
+ "summary": "Change a workflow app's web app; only the fields passed change"
+ },
+ "set.webapp.advanced_chat": {
+ "bind": {
+ "app_id": "path",
+ "chat_color_theme": "body",
+ "chat_color_theme_inverted": "body",
+ "copyright": "body",
+ "custom_disclaimer": "body",
+ "default_language": "body",
+ "description": "body",
+ "enabled": "body",
+ "icon": "body",
+ "icon_background": "body",
+ "icon_type": "body",
+ "input_placeholder": "body",
+ "privacy_policy": "body",
+ "show_workflow_steps": "body",
+ "title": "body",
+ "use_icon_as_answer_icon": "body"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "app_id": {},
+ "chat_color_theme": {},
+ "chat_color_theme_inverted": {},
+ "copyright": {},
+ "custom_disclaimer": {},
+ "default_language": {},
+ "description": {},
+ "enabled": {},
+ "icon": {},
+ "icon_background": {},
+ "icon_type": {},
+ "input_placeholder": {},
+ "privacy_policy": {},
+ "show_workflow_steps": {},
+ "title": {},
+ "use_icon_as_answer_icon": {}
+ },
+ "required": ["app_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "PATCH",
+ "path": "/openapi/v1/apps/{app_id}/webapp/advanced-chat",
+ "summary": "Change an advanced-chat app's web app; only the fields passed change"
+ },
+ "set.webapp.chat": {
+ "bind": {
+ "app_id": "path",
+ "chat_color_theme": "body",
+ "chat_color_theme_inverted": "body",
+ "copyright": "body",
+ "custom_disclaimer": "body",
+ "default_language": "body",
+ "description": "body",
+ "enabled": "body",
+ "icon": "body",
+ "icon_background": "body",
+ "icon_type": "body",
+ "input_placeholder": "body",
+ "privacy_policy": "body",
+ "title": "body",
+ "use_icon_as_answer_icon": "body"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "app_id": {},
+ "chat_color_theme": {},
+ "chat_color_theme_inverted": {},
+ "copyright": {},
+ "custom_disclaimer": {},
+ "default_language": {},
+ "description": {},
+ "enabled": {},
+ "icon": {},
+ "icon_background": {},
+ "icon_type": {},
+ "input_placeholder": {},
+ "privacy_policy": {},
+ "title": {},
+ "use_icon_as_answer_icon": {}
+ },
+ "required": ["app_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "PATCH",
+ "path": "/openapi/v1/apps/{app_id}/webapp/chat",
+ "summary": "Change a chat app's web app; only the fields passed change"
+ },
+ "set.webapp.agent_chat": {
+ "bind": {
+ "app_id": "path",
+ "chat_color_theme": "body",
+ "chat_color_theme_inverted": "body",
+ "copyright": "body",
+ "custom_disclaimer": "body",
+ "default_language": "body",
+ "description": "body",
+ "enabled": "body",
+ "icon": "body",
+ "icon_background": "body",
+ "icon_type": "body",
+ "input_placeholder": "body",
+ "privacy_policy": "body",
+ "title": "body",
+ "use_icon_as_answer_icon": "body"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "app_id": {},
+ "chat_color_theme": {},
+ "chat_color_theme_inverted": {},
+ "copyright": {},
+ "custom_disclaimer": {},
+ "default_language": {},
+ "description": {},
+ "enabled": {},
+ "icon": {},
+ "icon_background": {},
+ "icon_type": {},
+ "input_placeholder": {},
+ "privacy_policy": {},
+ "title": {},
+ "use_icon_as_answer_icon": {}
+ },
+ "required": ["app_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "PATCH",
+ "path": "/openapi/v1/apps/{app_id}/webapp/agent-chat",
+ "summary": "Change an agent-chat app's web app; only the fields passed change"
+ },
+ "set.webapp.completion": {
+ "bind": {
+ "app_id": "path",
+ "copyright": "body",
+ "custom_disclaimer": "body",
+ "default_language": "body",
+ "description": "body",
+ "enabled": "body",
+ "icon": "body",
+ "icon_background": "body",
+ "icon_type": "body",
+ "privacy_policy": "body",
+ "title": "body"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "app_id": {},
+ "copyright": {},
+ "custom_disclaimer": {},
+ "default_language": {},
+ "description": {},
+ "enabled": {},
+ "icon": {},
+ "icon_background": {},
+ "icon_type": {},
+ "privacy_policy": {},
+ "title": {}
+ },
+ "required": ["app_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "PATCH",
+ "path": "/openapi/v1/apps/{app_id}/webapp/completion",
+ "summary": "Change a completion app's web app; only the fields passed change"
+ },
+ "set.webapp.agent": {
+ "bind": {
+ "app_id": "path",
+ "chat_color_theme": "body",
+ "chat_color_theme_inverted": "body",
+ "copyright": "body",
+ "custom_disclaimer": "body",
+ "default_language": "body",
+ "description": "body",
+ "enabled": "body",
+ "icon": "body",
+ "icon_background": "body",
+ "icon_type": "body",
+ "input_placeholder": "body",
+ "privacy_policy": "body",
+ "title": "body",
+ "use_icon_as_answer_icon": "body"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "app_id": {},
+ "chat_color_theme": {},
+ "chat_color_theme_inverted": {},
+ "copyright": {},
+ "custom_disclaimer": {},
+ "default_language": {},
+ "description": {},
+ "enabled": {},
+ "icon": {},
+ "icon_background": {},
+ "icon_type": {},
+ "input_placeholder": {},
+ "privacy_policy": {},
+ "title": {},
+ "use_icon_as_answer_icon": {}
+ },
+ "required": ["app_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "PATCH",
+ "path": "/openapi/v1/apps/{app_id}/webapp/agent",
+ "summary": "Change an agent app's web app; only the fields passed change"
+ },
+ "set.service_api.agent": {
+ "bind": { "app_id": "path", "enabled": "body" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "app_id": {}, "enabled": {} },
+ "required": ["app_id", "enabled"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "PATCH",
+ "path": "/openapi/v1/apps/{app_id}/service-api/agent",
+ "summary": "Turn an agent app's Service API on or off"
+ },
+ "set.webapp_access.agent": {
+ "bind": { "access_mode": "body", "app_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "access_mode": {}, "app_id": {} },
+ "required": ["app_id", "access_mode"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "PUT",
+ "path": "/openapi/v1/apps/{app_id}/webapp-access/agent",
+ "summary": "Set who may open an agent app's web app (Enterprise)"
+ },
+ "get.marketplace.plugin": {
+ "bind": {
+ "category": "query",
+ "limit": "query",
+ "page": "query",
+ "query": "query",
+ "workspace_id": "path"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "category": {}, "limit": {}, "page": {}, "query": {}, "workspace_id": {} },
+ "required": ["workspace_id"]
+ },
+ "internal": false,
+ "kind": "list",
+ "method": "GET",
+ "path": "/openapi/v1/workspaces/{workspace_id}/marketplace/plugins",
+ "summary": "Search the marketplace for plugins to install; each hit says if it is installed here"
+ },
+ "get.plugin": {
+ "bind": { "category": "query", "workspace_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "category": {}, "workspace_id": {} },
+ "required": ["workspace_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/workspaces/{workspace_id}/plugins",
+ "summary": "Plugins installed in the workspace, with the provider ids each one adds"
+ },
+ "install.plugin": {
+ "bind": { "identifiers": "body", "workspace_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "identifiers": {}, "workspace_id": {} },
+ "required": ["workspace_id", "identifiers"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/workspaces/{workspace_id}/plugins:install",
+ "summary": "Start installing marketplace plugins; finishes in the background, check describe.plugin.task"
+ },
+ "describe.plugin.task": {
+ "bind": { "task_id": "path", "workspace_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "task_id": {}, "workspace_id": {} },
+ "required": ["task_id", "workspace_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/workspaces/{workspace_id}/plugin-tasks/{task_id}",
+ "summary": "Progress of a plugin install or upgrade; check again while pending or running"
+ },
+ "delete.plugin": {
+ "bind": { "plugin_id": "path", "workspace_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "plugin_id": {}, "workspace_id": {} },
+ "required": ["plugin_id", "workspace_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "DELETE",
+ "path": "/openapi/v1/workspaces/{workspace_id}/plugins/{plugin_id}",
+ "summary": "Uninstall a plugin from the workspace"
+ },
+ "describe.model_provider": {
+ "bind": { "provider": "path", "workspace_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "provider": {}, "workspace_id": {} },
+ "required": ["provider", "workspace_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/workspaces/{workspace_id}/model-providers/{provider}",
+ "summary": "One model provider with its credential form and saved credentials (names only)"
+ },
+ "create.model_provider.credential": {
+ "bind": { "credentials": "body", "name": "body", "provider": "path", "workspace_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "credentials": {}, "name": {}, "provider": {}, "workspace_id": {} },
+ "required": ["provider", "workspace_id", "credentials"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/workspaces/{workspace_id}/model-providers/{provider}/credentials",
+ "summary": "Save a credential for a model provider; the provider checks it first"
+ },
+ "get.model": {
+ "bind": {
+ "limit": "query",
+ "model_type": "query",
+ "page": "query",
+ "provider": "query",
+ "query": "query",
+ "workspace_id": "path"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "limit": {},
+ "model_type": {},
+ "page": {},
+ "provider": {},
+ "query": {},
+ "workspace_id": {}
+ },
+ "required": ["workspace_id"]
+ },
+ "internal": false,
+ "kind": "list",
+ "method": "GET",
+ "path": "/openapi/v1/workspaces/{workspace_id}/models",
+ "summary": "Models in the workspace across providers, with whether each can be used now"
+ },
+ "create.model.credential": {
+ "bind": {
+ "credentials": "body",
+ "model": "body",
+ "model_type": "body",
+ "name": "body",
+ "provider": "path",
+ "workspace_id": "path"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "credentials": {},
+ "model": {},
+ "model_type": {},
+ "name": {},
+ "provider": {},
+ "workspace_id": {}
+ },
+ "required": ["provider", "workspace_id", "model", "model_type", "credentials"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/workspaces/{workspace_id}/model-providers/{provider}/models/credentials",
+ "summary": "Save a credential for one model you name, for providers such as OpenAI-compatible or Ollama"
+ },
+ "get.tool": {
+ "bind": {
+ "limit": "query",
+ "page": "query",
+ "provider": "query",
+ "provider_type": "query",
+ "query": "query",
+ "workspace_id": "path"
+ },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": {
+ "limit": {},
+ "page": {},
+ "provider": {},
+ "provider_type": {},
+ "query": {},
+ "workspace_id": {}
+ },
+ "required": ["workspace_id"]
+ },
+ "internal": false,
+ "kind": "list",
+ "method": "GET",
+ "path": "/openapi/v1/workspaces/{workspace_id}/tools",
+ "summary": "Tools a workflow can call here, each with a ready tool node data"
+ },
+ "describe.tool_provider": {
+ "bind": { "provider": "path", "workspace_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "provider": {}, "workspace_id": {} },
+ "required": ["provider", "workspace_id"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "GET",
+ "path": "/openapi/v1/workspaces/{workspace_id}/tool-providers/{provider}",
+ "summary": "One tool provider with its API-key form and saved credentials (names only)"
+ },
+ "create.tool_provider.credential": {
+ "bind": { "credentials": "body", "name": "body", "provider": "path", "workspace_id": "path" },
+ "deprecated": false,
+ "input": {
+ "type": "object",
+ "properties": { "credentials": {}, "name": {}, "provider": {}, "workspace_id": {} },
+ "required": ["provider", "workspace_id", "credentials"]
+ },
+ "internal": false,
+ "kind": "object",
+ "method": "POST",
+ "path": "/openapi/v1/workspaces/{workspace_id}/tool-providers/{provider}/credentials",
+ "summary": "Save an API-key credential for a tool provider; the provider checks it first"
}
}
}
diff --git a/cli/test/fixtures/dify-mock/scenarios.ts b/cli/test/fixtures/dify-mock/scenarios.ts
index 8316192fe92..2fb6c78359f 100644
--- a/cli/test/fixtures/dify-mock/scenarios.ts
+++ b/cli/test/fixtures/dify-mock/scenarios.ts
@@ -6,6 +6,7 @@ export type Scenario =
| 'denied'
| 'expired'
| 'auth-expired'
+ | 'forbidden'
| 'rate-limited'
| 'server-5xx'
| 'slow-down'
@@ -36,7 +37,6 @@ export type WorkspaceFixture = {
name: string
role: string
status: string
- is_current: boolean
}
export type AppFixture = {
@@ -81,14 +81,12 @@ export const WORKSPACES: WorkspaceFixture[] = [
name: 'Default',
role: 'owner',
status: 'normal',
- is_current: true,
},
{
id: 'ws-2',
name: 'Other',
role: 'normal',
status: 'normal',
- is_current: false,
},
]
diff --git a/cli/test/fixtures/dify-mock/server.test.ts b/cli/test/fixtures/dify-mock/server.test.ts
index 5eabcc5539b..49ee8b24079 100644
--- a/cli/test/fixtures/dify-mock/server.test.ts
+++ b/cli/test/fixtures/dify-mock/server.test.ts
@@ -75,8 +75,6 @@ describe('dify-mock fixture server', () => {
expect(body.data).toHaveLength(2)
expect(body.data[0]?.id).toBe('ws-1')
expect(body.data[0]?.status).toBe('normal')
- expect(body.data[0]?.current).toBe(true)
- expect(body.data[1]?.current).toBe(false)
expect(body.hints).toEqual([])
})
diff --git a/cli/test/fixtures/dify-mock/server.ts b/cli/test/fixtures/dify-mock/server.ts
index cfd8d97cdf8..4dc78c65ae6 100644
--- a/cli/test/fixtures/dify-mock/server.ts
+++ b/cli/test/fixtures/dify-mock/server.ts
@@ -44,6 +44,8 @@ export type DifyMock = {
lastRequest: LastRequest | null
/** Number of requests received, including GET _catalog */
requestCount: number
+ /** Runs before each device-token poll is answered: lets a test act while a resume waits. */
+ onDeviceTokenPoll: (hook: () => void) => void
}
const TOKEN_RE = /^Bearer\s+dfo[ae]_[\w-]+$/
@@ -53,6 +55,7 @@ const EMPTY_ERROR_PATH = '/empty-error'
const BAD_VERIFICATION_URI = 'ftp://elsewhere.example/device'
const HANG_MS = 30_000
const OAUTH_PREFIX = '/openapi/v1/oauth/'
+export const FORBIDDEN_HINT = 'ask a workspace owner for the editor role'
const ServerErrorCode = {
Unauthorized: 'unauthorized',
@@ -71,6 +74,7 @@ const OpId = {
ChatRun: 'run.console_app.chat',
AdvancedChatRun: 'run.console_app.advanced_chat',
FormSubmit: 'submit.run.form',
+ RunEvents: 'get.run.event',
} as const
const CATALOG_STALE_MESSAGE =
@@ -195,7 +199,13 @@ function streamingRunResponse(
function hitlPauseResponse(appId: string): string {
return sseChunks([
- { event: 'workflow_started', data: { id: 'wf-run-hitl-1', workflow_id: 'wf-1' } },
+ {
+ event: 'workflow_started',
+ data: {
+ workflow_run_id: 'wf-run-hitl-1',
+ data: { id: 'wf-run-hitl-1', workflow_id: 'wf-1' },
+ },
+ },
{ event: 'node_started', data: { id: 'n1', title: 'First Node' } },
{
event: 'human_input_required',
@@ -255,6 +265,7 @@ export type MockState = {
lastImportBody: Record<string, unknown> | null
lastRequest: LastRequest | null
requestCount: number
+ beforeDeviceToken?: () => void
}
async function readMultipartRunBody(
@@ -435,6 +446,8 @@ export function buildApp(getScenario: () => Scenario, state?: MockState): Hono {
return c.json({ code: 'forbidden', message: 'resource_not_authorized', status: 403 }, 403)
const scenario = getScenario()
if (scenario === 'auth-expired') return unauthorized()
+ if (scenario === 'forbidden')
+ return errorResponse(ServerErrorCode.Forbidden, 'you may not do this', 403, FORBIDDEN_HINT)
await next()
})
@@ -548,7 +561,6 @@ export function buildApp(getScenario: () => Scenario, state?: MockState): Hono {
name: w.name,
role: getScenario() === 'resource-token' ? '' : w.role,
status: w.status,
- current: w.is_current,
}))
const total = rows.length
const hasMore = page * limit < total
@@ -562,6 +574,12 @@ export function buildApp(getScenario: () => Scenario, state?: MockState): Hono {
})
})
+ app.get('/openapi/v1/workspaces/:wsId', (c) => {
+ const ws = WORKSPACES.find((w) => w.id === c.req.param('wsId'))
+ if (ws === undefined) return errorResponse(ServerErrorCode.NotFound, 'workspace not found', 404)
+ return c.json({ id: ws.id, name: ws.name, role: ws.role, status: ws.status, created_at: null })
+ })
+
// Reachable only under the `catalog-changed` scenario: the op that catalog v2 adds.
app.get('/openapi/v1/workspaces/:wsId/ping', (c) => c.json({ ok: true }))
@@ -747,9 +765,18 @@ export function buildApp(getScenario: () => Scenario, state?: MockState): Hono {
return c.json({ result: 'success' })
})
- app.post('/openapi/v1/apps/:id/human-input-forms/:formToken:submit', (c) => {
- return c.json({})
- })
+ // Like the server: the submit names the run to follow, stopping at the next pause.
+ app.post('/openapi/v1/apps/:id/human-input-forms/:formToken:submit', (c) =>
+ c.json({
+ hints: [
+ {
+ summary: 'Follow the run',
+ op: OpId.RunEvents,
+ input: { app_id: c.req.param('id'), task_id: 'wf-run-hitl-1', continue_on_pause: false },
+ },
+ ],
+ }),
+ )
app.get('/openapi/v1/apps/:id/tasks/:task_id/events', (_c) => sseResponse(hitlResumedResponse()))
@@ -777,6 +804,7 @@ export function buildApp(getScenario: () => Scenario, state?: MockState): Hono {
})
app.post('/openapi/v1/oauth/device/token', async (c) => {
+ state?.beforeDeviceToken?.()
const scenario = getScenario()
if (scenario === 'denied')
return c.json({ error: 'access_denied', error_description: 'user rejected' }, { status: 400 })
@@ -872,6 +900,9 @@ export function startMock(opts: DifyMockOptions = {}): Promise<DifyMock> {
get requestCount() {
return state.requestCount
},
+ onDeviceTokenPoll(hook) {
+ state.beforeDeviceToken = hook
+ },
})
})
server.on('error', reject)
diff --git a/cli/test/fixtures/kernel.ts b/cli/test/fixtures/kernel.ts
index e0aaba23d49..ad4217df46b 100644
--- a/cli/test/fixtures/kernel.ts
+++ b/cli/test/fixtures/kernel.ts
@@ -80,7 +80,6 @@ export async function testContext(opts: TestWorldOptions): Promise<TestWorld> {
const restoreEnv = applyEnv({
[ENV.ConfigDir]: dir,
- [ENV.CacheDir]: dir,
[ENV.Server]: opts.env === true ? mock.url : undefined,
[ENV.Token]: opts.env === true ? ENV_LOGIN_TOKEN : undefined,
[ENV.WorkspaceId]: undefined,
diff --git a/cli/test/setup.ts b/cli/test/setup.ts
index 70ec0406c20..a869384bc1f 100644
--- a/cli/test/setup.ts
+++ b/cli/test/setup.ts
@@ -3,3 +3,4 @@
;(globalThis as unknown as Record<string, string>).__DIFYCTL_BUILD_DATE__ =
'1970-01-01T00:00:00.000Z'
;(globalThis as unknown as Record<string, string>).__DIFYCTL_CHANNEL__ = 'dev'
+;(globalThis as unknown as Record<string, boolean>).__DIFYCTL_COMPILED__ = false
diff --git a/cli/test/skills/tree.test.ts b/cli/test/skills/tree.test.ts
new file mode 100644
index 00000000000..74369e0f12e
--- /dev/null
+++ b/cli/test/skills/tree.test.ts
@@ -0,0 +1,202 @@
+import type { CommandConstructor } from '@/plugins/commands/command'
+import type { CommandTree } from '@/plugins/commands/registry'
+import { readdir, readFile } from 'node:fs/promises'
+import { dirname, join, normalize, relative, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vite-plus/test'
+import { commandTree } from '@/commands/tree.generated'
+import { parseCatalog } from '@/plugins/catalog'
+import { HELP_WORD } from '@/plugins/commands/command'
+import { mergeTrees, nodeAt } from '@/plugins/commands/registry'
+import { GLOBAL_INPUT } from '@/plugins/global-flags'
+import { opsTree } from '@/plugins/ops/tree'
+import { propertiesOf } from '@/protocol/shape'
+import { propertyFor } from '@/util/flag-name'
+
+const SKILL_DIR = fileURLToPath(new URL('../../../skills/difyctl/', import.meta.url))
+const CATALOG = fileURLToPath(new URL('../fixtures/catalog.json', import.meta.url))
+const ROOT_DOC = 'SKILL.md'
+const MAX_HOPS = 2
+const LEAF_DEPTH = MAX_HOPS
+const MAP_MAX_LINES = 60
+const TOC_AFTER_LINES = 100
+const TOC_HEADING = '## Contents'
+const H2 = /^## .*$/m
+const LINK = /\]\(([^)#\s]+\.md)\)/g
+const COMMAND = /`difyctl ([^`]+)`/g
+const FENCE = /^(`{3,})/
+const CONTINUATION = /\\\s*\n\s*/g
+const CODE_COMMAND = /^difyctl (.+)$/
+const PIPE = ' | '
+const FLAG = /(?:^|\s)--([a-z][a-z0-9-]*)/g
+const PLACEHOLDER = /^<[^>]+>$/
+const WORD = /^[a-z_]+(?:-[a-z_]+)*$/
+const DOTTED_ID = /^[a-z_]+(?:\.[a-z_]+)+$/
+const SPAN = /`([^`]+)`/g
+const NON_WORD_START = /^[-<]/
+const GLOBAL_FLAGS = [...Object.keys(GLOBAL_INPUT.shape), HELP_WORD]
+
+async function docs(): Promise<string[]> {
+ const out: string[] = []
+ for (const entry of await readdir(SKILL_DIR, { recursive: true, withFileTypes: true })) {
+ if (entry.isFile() && entry.name.endsWith('.md'))
+ out.push(relative(SKILL_DIR, join(entry.parentPath, entry.name)).split(sep).join('/'))
+ }
+ return out
+}
+
+function links(doc: string, text: string): string[] {
+ return [...text.matchAll(LINK)].map((m) =>
+ normalize(join(dirname(doc), m[1] as string))
+ .split(sep)
+ .join('/'),
+ )
+}
+
+function depths(text: ReadonlyMap<string, string>): Map<string, number> {
+ const depth = new Map([[ROOT_DOC, 0]])
+ const queue = [ROOT_DOC]
+ while (queue.length > 0) {
+ const doc = queue.shift() as string
+ for (const next of links(doc, text.get(doc) ?? '')) {
+ if (depth.has(next)) continue
+ depth.set(next, (depth.get(doc) as number) + 1)
+ queue.push(next)
+ }
+ }
+ return depth
+}
+
+/** `difyctl` command lines inside fenced code blocks, with `\` continuations joined. */
+function fencedCommands(body: string): string[] {
+ const code: string[] = []
+ let fence: string | undefined
+ for (const line of body.split('\n')) {
+ const open = FENCE.exec(line.trim())?.[1]
+ if (fence === undefined) {
+ if (open !== undefined) fence = open
+ } else if (open !== undefined && open.length >= fence.length && line.trim() === open) {
+ fence = undefined
+ } else {
+ code.push(line)
+ }
+ }
+ return code
+ .join('\n')
+ .replace(CONTINUATION, ' ')
+ .split('\n')
+ .map((line) => CODE_COMMAND.exec(line.trim())?.[1])
+ .filter((span): span is string => span !== undefined)
+}
+
+function leadingWords(span: string): string[] {
+ const words: string[] = []
+ for (const word of span.split(' ')) {
+ if (!WORD.test(word)) break
+ words.push(word)
+ }
+ return words
+}
+
+/**
+ * The commands a line names: the exact command, or — when a `<placeholder>` follows a
+ * group — every command one word below it.
+ */
+function commandsNamed(tree: CommandTree, span: string, words: readonly string[]) {
+ const node = nodeAt(tree, words)
+ if (node === undefined) return []
+ if (node.command !== undefined) return [node.command]
+ if (!PLACEHOLDER.test(span.split(' ')[words.length] ?? '')) return []
+ return Object.values(node.subcommands)
+ .map((child) => child.command)
+ .filter((command): command is CommandConstructor => command !== undefined)
+}
+
+function flagsOf(command: CommandConstructor): string[] {
+ return [...Object.keys(propertiesOf(command.flags())), ...GLOBAL_FLAGS]
+}
+
+function typedFlags(span: string): string[] {
+ return [...(span.split(PIPE)[0] as string).matchAll(FLAG)].map((m) => propertyFor(m[1] as string))
+}
+
+describe('skills/difyctl tree', async () => {
+ const all = await docs()
+ const text = new Map(
+ await Promise.all(
+ all.map(async (d) => [d, await readFile(join(SKILL_DIR, d), 'utf8')] as const),
+ ),
+ )
+ const catalog = parseCatalog(await readFile(CATALOG)).ops
+ const ops = Object.keys(catalog)
+ const { tree } = mergeTrees(commandTree, opsTree(catalog))
+ const depth = depths(text)
+ const commands = [...text].flatMap(([doc, body]) => [
+ ...[...body.matchAll(COMMAND)].map((m) => ({ doc, span: m[1] as string })),
+ ...fencedCommands(body).map((span) => ({ doc, span })),
+ ])
+
+ it('every relative link resolves', () => {
+ for (const [doc, body] of text)
+ for (const target of links(doc, body)) expect(all, `${doc} → ${target}`).toContain(target)
+ })
+
+ it('every doc is reachable within two hops of SKILL.md', () => {
+ for (const doc of all) {
+ expect(depth.has(doc), `${doc} unreachable`).toBe(true)
+ expect(depth.get(doc) as number, doc).toBeLessThanOrEqual(MAX_HOPS)
+ }
+ })
+
+ it('maps stay short and leaves link only to siblings', () => {
+ for (const [doc, body] of text) {
+ if ((depth.get(doc) as number) < LEAF_DEPTH) {
+ expect(body.split('\n').length, doc).toBeLessThan(MAP_MAX_LINES)
+ continue
+ }
+ for (const target of links(doc, body))
+ expect(dirname(target), `${doc} → ${target}`).toBe(dirname(doc))
+ }
+ })
+
+ it('long leaves open with contents', () => {
+ for (const [doc, body] of text) {
+ if ((depth.get(doc) as number) < LEAF_DEPTH) continue
+ if (body.split('\n').length <= TOC_AFTER_LINES) continue
+ expect(H2.exec(body)?.[0], doc).toBe(TOC_HEADING)
+ }
+ })
+
+ it('every difyctl command exists locally or in the catalog', () => {
+ for (const { doc, span } of commands) {
+ const words = leadingWords(span)
+ if (words.length === 0) {
+ expect(span, `${doc}: difyctl ${span} names no command`).toMatch(NON_WORD_START)
+ continue
+ }
+ const found = words[0] === HELP_WORD || nodeAt(tree, words) !== undefined
+ expect(found, `${doc}: difyctl ${span}`).toBe(true)
+ }
+ })
+
+ it('every flag on a command is one that command parses', () => {
+ for (const { doc, span } of commands) {
+ const named = commandsNamed(tree, span, leadingWords(span))
+ if (named.length === 0) continue
+ const allowed = new Set(named.flatMap(flagsOf))
+ for (const flag of typedFlags(span))
+ expect(allowed.has(flag), `${doc}: difyctl ${span}: ${flag}`).toBe(true)
+ }
+ })
+
+ it('every dotted op id exists in the catalog', () => {
+ const verbs = new Set(ops.map((op) => op.split('.')[0]))
+ for (const [doc, body] of text) {
+ for (const m of body.matchAll(SPAN)) {
+ const span = m[1] as string
+ if (!DOTTED_ID.test(span) || !verbs.has(span.split('.')[0])) continue
+ expect(ops, `${doc}: ${span}`).toContain(span)
+ }
+ }
+ })
+})
diff --git a/cli/vite.config.ts b/cli/vite.config.ts
index a7381e317ca..755aee4c4be 100644
--- a/cli/vite.config.ts
+++ b/cli/vite.config.ts
@@ -29,6 +29,7 @@ export default defineConfig({
__DIFYCTL_COMMIT__: JSON.stringify(buildInfo.commit),
__DIFYCTL_BUILD_DATE__: JSON.stringify(buildInfo.buildDate),
__DIFYCTL_CHANNEL__: JSON.stringify(buildInfo.channel),
+ __DIFYCTL_COMPILED__: 'false',
},
},
test: {
diff --git a/cli/vitest.e2e.config.ts b/cli/vitest.e2e.config.ts
index 3c3a1347ef1..23c08ba2da9 100644
--- a/cli/vitest.e2e.config.ts
+++ b/cli/vitest.e2e.config.ts
@@ -49,6 +49,7 @@ export default defineConfig({
__DIFYCTL_COMMIT__: JSON.stringify(buildInfo.commit),
__DIFYCTL_BUILD_DATE__: JSON.stringify(buildInfo.buildDate),
__DIFYCTL_CHANNEL__: JSON.stringify(buildInfo.channel),
+ __DIFYCTL_COMPILED__: 'false',
},
},
test: {
diff --git a/skills/README.md b/skills/README.md
index 65015a5ed6e..971f617e962 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -1,26 +1,34 @@
-# difyctl skills
+# difyctl skill
-Agent skills for the difyctl CLI. They use the standard Agent Skills layout: one
-folder per skill, each with a `SKILL.md`. There is no index to maintain.
+One agent skill for the difyctl CLI: `skills/difyctl/`. It uses the standard
+Agent Skills layout. `SKILL.md` is the root; the docs it links to sit under
+`references/`.
-`difyctl install skills <dir>` downloads them from GitHub at install time, from
-the commit that difyctl was built from. `--from` points at any GitHub folder
-with the same layout, or at a local folder. The same files install through the
-Vercel installer: `npx skills add langgenius/dify --skill difyctl -g`.
+The difyctl binary carries a built-in copy. `difyctl install skills <dir>`
+writes that copy into `<dir>`. `--from <folder>` installs a local folder with
+the same layout instead. The same files install through the Vercel installer:
+`npx skills add langgenius/dify --skill difyctl -g`.
-## Adding a skill
+## Changing the skill
-- One folder per skill: `difyctl` is the base skill, scenario skills are
- `difyctl-<scenario>`.
-- `SKILL.md` frontmatter has `name` (equal to the folder name: lowercase
- letters, digits, dashes) and `description`. The description says when to use
- the skill; the base skill quotes it.
-- Any files may sit beside `SKILL.md`: `references/`, `scripts/`, `assets/`.
- Commit scripts as executable (`chmod +x`); the installer keeps the bit.
-- A scenario skill opens with: Read `../difyctl/SKILL.md` first.
-- Every `difyctl <command>` named in backticks must exist in the command tree.
- Every dotted op id must exist in `cli/test/fixtures/catalog.json`.
-- List every scenario skill in the base skill's "Other skills" section.
+The skill is a tree of linked docs, so an agent reads only the branch it needs.
-A change here reaches users with the next difyctl build. Anyone can get it
-sooner with `--from https://github.com/langgenius/dify/tree/main/skills`.
+- `SKILL.md` frontmatter has `name` (`difyctl`) and `description`. The
+ description says when to use the skill.
+- `SKILL.md` and the docs it links to are maps. Keep each map under 60 lines.
+- The docs one level further down are leaves. A leaf may link only to other
+ leaves in its own folder.
+- Every doc is at most 2 hops from `SKILL.md`.
+- Write links as "Read X when ...", so the agent knows when to follow them.
+- In a leaf over 100 lines, `## Contents` is the first `##` heading.
+- Put each fact in one place and link to it from elsewhere.
+- Any file in `skills/difyctl/` ships. Files starting with `#!` are installed
+ executable.
+
+`cli/test/skills/tree.test.ts` checks links, depth, sizes, and every `difyctl`
+command, in backticks or in code blocks. Each command must exist locally or in
+`cli/test/fixtures/catalog.json`, and each flag must be one that command
+parses. Add an op's descriptor there when a doc starts
+naming it.
+
+A change here reaches users with the next difyctl build.
diff --git a/skills/difyctl/SKILL.md b/skills/difyctl/SKILL.md
index e62b3ccece6..9689c1d901d 100644
--- a/skills/difyctl/SKILL.md
+++ b/skills/difyctl/SKILL.md
@@ -1,6 +1,6 @@
---
name: difyctl
-description: 'Base skill for the difyctl CLI: find any command or Dify operation through help and run it as a command. Use when the task involves difyctl or a Dify server from the command line.'
+description: 'Operate a Dify server through difyctl: find and run any operation, and build, test, publish and change Workflow and Chatflow apps. Use when the task involves difyctl, a Dify server, or Dify apps.'
---
# difyctl
@@ -9,6 +9,8 @@ difyctl talks to a Dify server. Business commands are not built in: the server p
Always pass `--json`. Help and errors are text on a terminal and JSON in a pipe; `--json` (or `DIFY_OUTPUT=json`) forces JSON. Results and streams are always JSON.
+Operations that remove or revoke have no confirmation prompt. Confirm with the human first.
+
## Finding what the CLI can do
An operation id is dotted, `run.console_app.chat`, and is typed as words: `difyctl run console_app chat`. Ids come from the server and can change, so look them up instead of assuming them.
@@ -24,36 +26,9 @@ Four views under `help`, covering local commands and server operations as one tr
Not logged in, or the server unreachable, gives the local commands plus one line on stderr.
-## Running an operation
-
-`difyctl run console_app workflow --app-id <id> --inputs '{"a":1}'`. Each top-level field of `input` is a flag, dashes for underscores. Scalars take a value; objects, maps and lists of objects take a JSON literal or `@file.json`; lists of scalars repeat the flag. Fields named `input`, `stream`, `only`, `output`, `verbose`, `json` or `help` have no flag; pass them through `--input`.
-
-`--input '{"a":1}'`, `--input @file.json` or `--input @-` (stdin) sends the whole body; field flags merge over it. A dotted id is a command with the dots as spaces: `run.console_app.workflow` is `difyctl run console_app workflow`.
-
-Run an app with the op for its mode: `run console_app workflow`, `run console_app chat`, `run console_app advanced_chat`, `run console_app completion`. First `difyctl describe console_app --app-id <id> --json` and read `input_schema`; that is the shape of `inputs`. Local files go under `files`, keyed by the app's file variable name (`{"files":{"doc":"./r.pdf"}}` or a list of paths); files for the run itself under `attachments`; URLs straight into `inputs`.
-
-## difyctl-only flags
-
-`--stream` prints each event of a streaming op as one JSON line instead of folding them. `--only <event>` filters streamed events (repeatable). `--output <path>` saves a file-kind response; the default is the current directory under the server's filename, or `<op-id>.<ext>`. `--verbose` adds the raw server response to errors. A flag the operation's kind does not support exits 2.
-
-## Reading results
-
-Streaming ops fold to `{status, text, outputs?, total_tokens?, message_id?, conversation_id?, error?, hints}`. `text.answer` is the reply; `text.by_source` appears only while `status` is `incomplete`. `status` is `ended`, `failed` (exit 1), `suspended` (a form is waiting; follow `hints`) or `incomplete` (the stream broke early). Any response may carry `hints: [{summary, op, input, form?}]`, the server's next steps: next page, confirm step, reply op, form submit. Fill any `null` in `input` and pass it back with `difyctl <op, dots as spaces> --input '<input>'`.
-
-## Errors and exit codes
-
-Errors are one envelope on stderr: `{"error":{"code","message","hint"?,"details"?,"schema"?}}`. Exit 2 is bad input (schema included), 4 not logged in or forbidden, 6 catalog unavailable or unknown op (run `difyctl refresh cache` or upgrade difyctl), 7 rate limited.
-
-## Login and environment
-
-`difyctl login --server https://...` (device flow; `--no-browser` prints the URL and code; `--no-keyring` keeps the token in a file; `--insecure` skips TLS verification). One login at a time. `difyctl use workspace <id>` pins a workspace; `difyctl get workspace` shows them. Scripts skip login with `DIFY_SERVER` and `DIFY_TOKEN`; `DIFY_WORKSPACE_ID` overrides the pin; `DIFY_CONFIG_DIR` and `DIFY_CACHE_DIR` move the files.
-
-`login` blocks until the browser approval arrives. Run `difyctl login --server <url> --no-browser` as a background job, relay the `open <url>` and `code <code>` lines from its stderr to the user, and do not cancel the job. Its exit code reports the result. In a sandbox, add `--no-keyring` and set `DIFY_CONFIG_DIR` to persistent storage on every call, so the login survives the next session. If background jobs do not survive between calls, run `login --no-wait` instead, relay the `verification_uri` and `user_code` it prints, and after the user approves run `login --resume` until it stops printing `status: pending`.
-
-## Destructive operations
-
-Operations that remove or revoke have no confirmation prompt. Confirm with the person first.
-
-## Other skills
+## Where to read next
-Scenario skills add guidance for one kind of task. `difyctl get skills` shows them; `difyctl install skills <skills root> --skill <name>` installs one, where `<skills root>` is the folder above this file's folder. Re-running `difyctl install skills <skills root>` after upgrading difyctl refreshes every skill.
+- Read [`references/setup.md`](references/setup.md) to check login or log in, switching server or workspace, or running in a sandbox or CI.
+- Read [`references/operations.md`](references/operations.md) before running any operation: flags, inputs, files, results, hints, errors and exit codes.
+- Read [`references/build-workflow.md`](references/build-workflow.md) when asked to create, change, test or publish a Workflow or Chatflow app.
+- Read [`references/plugins.md`](references/plugins.md) to find tools, models and knowledge bases before building, when a plugin, model, tool or credential is missing, or when the human asks to install or remove a plugin.
diff --git a/skills/difyctl/references/build-workflow.md b/skills/difyctl/references/build-workflow.md
new file mode 100644
index 00000000000..8531836f7a3
--- /dev/null
+++ b/skills/difyctl/references/build-workflow.md
@@ -0,0 +1,35 @@
+# Build a Workflow or Chatflow app
+
+Four phases. Each ends with a gate; never skip one, even for a small app.
+
+1. **Spec**: agree what the app must do. Gate: the human approves `spec.md`.
+2. **Plan**: decide every node and config. Gate: the human approves `plan.md` and chooses how to build.
+3. **Build**: create the app and build it slice by slice. Gate: each slice passes its tests and review.
+4. **Hand over**: final checks, then publish and open access. Gate: the human says yes to going live.
+
+## Rules
+
+- Keep the working files in `difyctl/<app-slug>/` in the current folder: `spec.md`, `plan.md`, `app.yml`, and `live.yml` when changing an existing app.
+- Requirement ids (`R1`, `R2`, …) from the spec run through the plan, the build and the final report.
+- One writer per draft at a time.
+- Nothing goes live without the human's yes.
+- **Report problems; never work around them.** When something blocks the agreed design, stop and tell the human what you found and the options. Examples: a tool that isn't configured, a missing credential or plugin, a requirement a node can't meet, a check you can't pass. Never swap in a substitute on your own: an HTTP Request or Code node in place of a tool, prompt text in place of a knowledge base, a dropped or weakened requirement.
+- **Every change from the approved spec or plan needs the human's yes before you build it.** List each one: what changes, why, and what it costs. "Use defaults" or "go" approves only the options you already showed with your recommendation. It never approves a substitute you didn't show.
+- **Prefer an existing tool; the human picks.** For each outside service or model, rank the options: an installed and configured tool, then an official or partner plugin, then a workflow tool. HTTP Request or Code comes last. A missing key is not a reason to pick HTTP Request or Code: ask the human for it.
+
+## Read next
+
+- [`build-workflow/change.md`](build-workflow/change.md): read first when the app already exists.
+- [`build-workflow/spec.md`](build-workflow/spec.md): read in the spec phase.
+- [`build-workflow/plan.md`](build-workflow/plan.md): read in the plan phase.
+- [`build-workflow/build.md`](build-workflow/build.md): read in the build phase.
+- [`build-workflow/handover.md`](build-workflow/handover.md): read when the build is done.
+- [`build-workflow/dsl.md`](build-workflow/dsl.md): read when writing or reading app YAML.
+- Read [`plugins.md`](plugins.md) in the spec phase to find tools, models and knowledge bases, and when a plugin, model, tool or credential is missing.
+
+## Limits
+
+- A draft run paused on a human-input node can't be resumed over difyctl.
+- Trigger-started workflows (webhook, schedule, plugin) can't be draft-tested.
+- Loop and iteration nodes can't be tested alone; use a full draft run.
+- With an app's Service API off, difyctl can't find, describe, export (exit 4), test, run or publish it; only import works. An admin turns it on with `difyctl set service_api --app-id <app_id> --enabled`.
diff --git a/skills/difyctl/references/build-workflow/build.md b/skills/difyctl/references/build-workflow/build.md
new file mode 100644
index 00000000000..47117a59e2e
--- /dev/null
+++ b/skills/difyctl/references/build-workflow/build.md
@@ -0,0 +1,76 @@
+# Build phase
+
+Start only when the human approved the plan and chose how to build. `<mode>` is `workflow` for a Workflow app and `advanced_chat` for a Chatflow app.
+
+## Before the first slice
+
+When you change an existing app, skip creating it and the skeleton slice. Start from the current draft.
+
+Otherwise create the app once, and write its `app_id` into `plan.md`:
+
+```bash
+difyctl create console_app <mode> --name "<name>" --json
+```
+
+Build this one app; never make copies.
+
+## Each slice
+
+1. Export the draft. Keep `draft_hash`. Save `data` as `app.yml` on the first slice.
+
+ ```bash
+ difyctl export console_app dsl --app-id <app_id> --json
+ ```
+
+2. Write the slice's nodes and edges into `app.yml` from the node table. Make no new decisions. Read [dsl.md](dsl.md).
+3. Check the YAML. Fix every `error` by its `loc` and check again until `valid` is true.
+
+ ```bash
+ jq -Rs '{yaml_content: .}' difyctl/<app-slug>/app.yml |
+ difyctl check console_app dsl --app-id <app_id> --input @- --json
+ ```
+
+4. Import over the draft. Always send the YAML through stdin.
+
+ ```bash
+ jq -Rs '{yaml_content: .}' difyctl/<app-slug>/app.yml |
+ difyctl import console_app dsl --app-id <app_id> --mode yaml-content --draft-hash <draft_hash> --input @- --json
+ ```
+
+ - `completed`: go on. Export again before the next import; the hash changed.
+ - `completed-with-warnings`: stop and read `warnings`.
+ - `pending`: the DSL version differs from the server's. Show the human both versions. On a yes, run `difyctl confirm console_app dsl_import --import-id <id> --json`.
+ - `dsl_invalid`: fix the issues in `details` by `loc`.
+ - `draft_changed` (409, also on `confirm`): someone else edited the draft since your export. Export again, show the human the difference, and never overwrite it.
+ - Any other failure: stop and show the human the message.
+
+5. Test each new node alone. It reuses the last full run's values; override them with `--inputs`, keyed `#<node_id>.<var>#`. Give a file variable a local file with `--files '{"<variable>": "<path>"}'`.
+
+ ```bash
+ difyctl test node <mode> --app-id <app_id> --node-id <node_id> --inputs '{"#<node_id>.<var>#": "<value>"}' --json
+ ```
+
+6. Run the whole draft on the slice's acceptance cases; check each by its check type. Chatflow also takes `--query "<message>"`. Leave out `--inputs` when the start node has no variables.
+
+ ```bash
+ difyctl test console_app <mode> --app-id <app_id> --inputs '{"<var>": "<value>"}' --json
+ ```
+
+7. Review the slice against the plan, and the YAML against the node table.
+8. Tick the slice in `plan.md` with its run ids. A new session resumes at the first unticked slice.
+
+## When something fails
+
+Find the node that failed and what it received:
+
+```bash
+difyctl get run node --app-id <app_id> --run-id <run_id> --json
+```
+
+A fix that changes the plan or spec follows the next section.
+
+## Changes to the plan or spec
+
+Never build a change first and report it later; ask as the rules in `build-workflow.md` say. On a yes, update the plan (and the spec, if it changes), then the YAML. Log it under "Changes during build" with when the human approved it.
+
+The build phase never publishes.
diff --git a/skills/difyctl/references/build-workflow/change.md b/skills/difyctl/references/build-workflow/change.md
new file mode 100644
index 00000000000..a1705f08913
--- /dev/null
+++ b/skills/difyctl/references/build-workflow/change.md
@@ -0,0 +1,43 @@
+# Change an existing app
+
+Use this path when the app already exists. It reuses the four phases.
+
+1. Find the app and confirm with the human that it is the right one:
+
+ ```bash
+ difyctl get console_app --name <name> --json
+ ```
+
+ If the app is missing, its Service API may be off (see Limits in `build-workflow.md`). Ask the human for its id.
+
+2. Export first.
+ - List the versions. Note the `id` of the row with `current: true`: that is the live version.
+ - Export that version and save it as `difyctl/<app-slug>/live.yml`. This is the live baseline.
+ - Export the draft separately and keep its `draft_hash`. An export without `--workflow-id` returns the draft, not the live version.
+
+ ```bash
+ difyctl get console_app version --app-id <app_id> --json
+ difyctl export console_app dsl --app-id <app_id> --workflow-id <version_id> --json | jq -r .data > difyctl/<app-slug>/live.yml
+ difyctl export console_app dsl --app-id <app_id> --json
+ ```
+
+ If the draft differs from the live version, show the human the difference. Ask which one to start from. If the human picks live, import `live.yml` over the draft with the draft's `draft_hash`. Check the result as in [build.md](build.md).
+
+ ```bash
+ jq -Rs '{yaml_content: .}' difyctl/<app-slug>/live.yml |
+ difyctl import console_app dsl --app-id <app_id> --mode yaml-content --draft-hash <draft_hash> --input @- --json
+ ```
+
+ Publishing replaces the live version, so that version id is the one to go back to. To go back, copy it into the draft, then publish:
+
+ ```bash
+ difyctl restore console_app version --app-id <app_id> --version-id <version_id> --json
+ difyctl publish console_app --app-id <app_id> --json
+ ```
+
+ If restore fails, export the draft for a fresh `draft_hash`, import `live.yml` over the draft instead, then publish.
+
+3. If `difyctl/<app-slug>/` has no `spec.md`, the app was built elsewhere. Rebuild a baseline spec from the export: the graph, the requirements you can infer, the inputs and outputs. The human confirms it.
+4. Write the change as a "Change" section in the spec: new, changed and removed requirements and cases. Existing cases become regression cases.
+5. Plan only the nodes that change, in slices as usual. After you edit the export, run `difyctl check console_app dsl` on it before every import, as in [build.md](build.md).
+6. At the end, run every old case again. Then hand over as usual.
diff --git a/skills/difyctl/references/build-workflow/dsl.md b/skills/difyctl/references/build-workflow/dsl.md
new file mode 100644
index 00000000000..f8ece50be6c
--- /dev/null
+++ b/skills/difyctl/references/build-workflow/dsl.md
@@ -0,0 +1,39 @@
+# App DSL
+
+Start from an export of the app's draft. A new Workflow app's export is empty. A new Chatflow's is `start` → `llm` (no model, so `resource_unavailable`) → `answer` (`{{#llm.text#}}`). Keep the export's `version`, `kind`, `features`, `environment_variables` and `conversation_variables`.
+
+## Where things go
+
+- `app.mode` is `workflow` for a Workflow app and `advanced-chat` for a Chatflow app.
+- `workflow.graph.nodes[]`: `{id, type: custom, data: {type, title, version, ...}, position: {x, y}}`. The rest of `data`, and `version`, come from `difyctl describe node_type --node-type <type>`.
+- `workflow.graph.edges[]`: `{id, source, target, sourceHandle, targetHandle: target}`. `sourceHandle` is `source`, except on branch nodes:
+ - if-else: each case's `case_id`, plus `false` for else;
+ - question classifier: each class's `id`;
+ - human input: each `user_actions` id, plus `__timeout`;
+ - `error_strategy: fail-branch` adds a `fail-branch` handle for failure. Success still leaves by the node's usual handles: `source`, or the branch handles above.
+- Give every branch an edge, including `false` and `__timeout`.
+- End node output names must be unique across all End nodes.
+- A node id is any unique string. Never change the id of an existing node.
+- Read another node's output as `{{#<node_id>.<var>#}}` in text, and `[<node_id>, <var>]` in a `value_selector`.
+- An LLM node's `model` is the `node_model` of a row from `difyctl get model --model-type llm`, as the plan names it.
+- A knowledge-retrieval node starts from a row's `node_data` in `difyctl get knowledge_base`.
+- Never put secret values in the DSL.
+- Don't use `datasource` or `knowledge-index` nodes. They belong to knowledge pipelines.
+- An import over an existing app copies the YAML's `app.name`, description and icon onto the app.
+- Import fills empty containers, such as Start `variables` and tool parameter maps. It never fills in a model, classes or a prompt.
+
+## Tool node
+
+- Start from the tool's `node_data` in `difyctl get tool`. Put it in the node's `data` as it is.
+- Keep `tool_node_version: "2"`. Every value in `tool_parameters` and `tool_configurations` stays `{type, value}`.
+- Fill every `null` value: `{type: constant, value: …}`, `{type: mixed, value: "{{#node_id.var#}}"}`, or `{type: variable, value: [node_id, var]}`.
+- Leave out `credential_id`; the workspace's default credential is used.
+
+## The check
+
+`difyctl check console_app dsl` and the import run the same check. Each issue has a `code`, a `severity`, a `node_id`, a `loc` that points to the field, and a `message`.
+
+- An `error` stops the import. Fix it by its `loc`.
+- A `warning` does not stop the import, but the release check fails on it. Fix it, or report it to the human:
+ - `resource_unavailable`: a model, tool or plugin the workspace lacks. Runs fail on it.
+ - `branch_unconnected`: a branch with no edge. A run that takes it stops there.
diff --git a/skills/difyctl/references/build-workflow/handover.md b/skills/difyctl/references/build-workflow/handover.md
new file mode 100644
index 00000000000..e4a59f6b8cb
--- /dev/null
+++ b/skills/difyctl/references/build-workflow/handover.md
@@ -0,0 +1,49 @@
+# Hand-over phase
+
+Start when every slice in `plan.md` is ticked. `<mode>` is `workflow` or `advanced_chat`.
+
+1. Run every acceptance case in the spec on the draft. Report pass or fail per requirement and per case, with your reasoning for each `judged` case.
+2. Check the release, after the acceptance run so `tested` covers the current draft:
+
+ ```bash
+ difyctl check console_app release --app-id <app_id> --json
+ ```
+
+ Fix every item in `issues`. If `tested` fails, run the draft again. Go on only when `ready` is true.
+
+3. Stop at the human gate. Show in plain words: the `changes` against the published version, the `checks`, the acceptance results, the "Changes during build" list, and anything still open.
+4. On a yes, publish. Show any `warning` in the result. Then confirm the row whose `id` is the result's `version_id` shows `current: true`:
+
+ ```bash
+ difyctl publish console_app --app-id <app_id> --json
+ difyctl get console_app version --app-id <app_id> --json
+ ```
+
+5. Settle access. A new app starts with the web app and the Service API on. Ask the human about each one. `--enabled=false` turns a setting off.
+ - Web app. When it stays on, give the human the `url` from the result.
+
+ ```bash
+ difyctl set webapp <mode> --app-id <app_id> --enabled --json
+ ```
+
+ - Service API (needs an admin). Warn the human first what turning it off costs (see Limits in `build-workflow.md`), and note the app id. If the human wants it off, record that and turn it off after the smoke test in step 6: `difyctl run` fails with `service_api_disabled` while it is off.
+
+ ```bash
+ difyctl set service_api --app-id <app_id> --enabled --json
+ ```
+
+ - Who may open the web app (Enterprise): `public`, `private_all` or `sso_verified`. Picking members or groups (`private`) is done in the Dify console. `difyctl run` obeys this too, so the logged-in account must be allowed for the smoke test. `public` exits 4 with `webapp_public_access_disabled` when the server disables public web apps; offer the human `private_all` or `sso_verified`.
+
+ ```bash
+ difyctl set webapp_access --app-id <app_id> --access-mode <access_mode> --json
+ ```
+
+6. Smoke test the live app with one acceptance case. Chatflow also takes `--query "<message>"`.
+
+ ```bash
+ difyctl run console_app <mode> --app-id <app_id> --inputs '{"<var>": "<value>"}' --json
+ ```
+
+ Then, if the human chose to turn the Service API off in step 5, turn it off now with `--enabled=false`.
+
+7. Close. Mark `plan.md` as published with the `version_id`, the date and the url. Give the human a short summary that lists every change from the spec and plan, and when the human approved it.
diff --git a/skills/difyctl/references/build-workflow/plan.md b/skills/difyctl/references/build-workflow/plan.md
new file mode 100644
index 00000000000..c1b24d4f990
--- /dev/null
+++ b/skills/difyctl/references/build-workflow/plan.md
@@ -0,0 +1,58 @@
+# Plan phase
+
+Start only when the human has approved `spec.md`. The plan phase ends when the human approves `difyctl/<app-slug>/plan.md` and chooses how to build.
+
+## How to plan
+
+1. Turn each spec step into nodes. Use only node types `difyctl get node_type` lists. Read each type's schema, defaults and `version` with `difyctl describe node_type --node-type <type>`.
+2. Settle every config in full, so the build only changes format:
+ - LLM: model, prompt text and outputs.
+ - If-else: conditions, and where each branch goes.
+ - Tool: the row from `difyctl get tool --provider <id>`, and a value for every parameter. Never guess one.
+ - Human input: the form, the actions, the timeout, and where each action and `__timeout` goes.
+ - Code: the code itself.
+ - Variable references, written as `{{#node_id.var#}}`.
+3. Draw the node-level Mermaid graph with real node ids, every edge, and a label on every branch.
+4. Cut the build into slices. Each slice is small and connected, and imports and runs on its own. Slice 1 is the skeleton: start → end (Chatflow: start → answer; set the starter `llm` node's model or remove it and rewrite `answer`) with the final inputs and outputs.
+5. Map the tests: a `difyctl test node <mode>` call with inputs for each new node, and a full draft run (`difyctl test console_app <mode>`) at the end of each slice on the cases it can pass. `<mode>` is `workflow` or `advanced_chat`.
+6. Check coverage. Every requirement maps to a node and a test. Every resource is confirmed, and each chosen plugin is installed and configured. An open resource blocks approval.
+7. Ask the human to review the plan, and to choose how to build:
+ - you build it alone; or
+ - one fresh subagent per slice, one after another, given the slice text, the file paths and the `app_id`. A reviewer subagent checks each slice. Never run two on one app at once: their imports collide on the draft hash.
+
+## Template
+
+Copy this into `plan.md` and fill it in.
+
+````markdown
+# <App name>: plan
+
+App: <name>. Mode: <workflow or advanced_chat>. `app_id`: <filled in at build>. Spec: spec.md.
+
+## Node graph
+
+```mermaid
+flowchart LR
+ start --> classify
+ classify -- order --> order_llm --> answer
+ classify -- other --> answer
+```
+
+## Node table
+
+| Id | Type | Version | Title | Config | Inputs used | Outputs | Covers |
+| --------- | ---- | ------- | ----------- | ---------------------------------------------------- | ----------------- | ------- | ------ |
+| order_llm | llm | 1 | Order reply | model: <provider>/<model>; system prompt: "<prompt>" | `{{#sys.query#}}` | text | R1 |
+
+## Slices
+
+- [ ] Slice 2: add `classify`, `order_llm`. Covers R1. Node tests: `order_llm` with query "Où est ma commande ?". Full run: A1. Runs: <run ids>
+
+## Test map
+
+- A1: `test console_app advanced_chat`, query "Où est ma commande ?", judged.
+
+## Changes during build
+
+- <what changed>: <why>. Cost if wrong: <cost>. Approved: <when>.
+````
diff --git a/skills/difyctl/references/build-workflow/spec.md b/skills/difyctl/references/build-workflow/spec.md
new file mode 100644
index 00000000000..aa0b016305a
--- /dev/null
+++ b/skills/difyctl/references/build-workflow/spec.md
@@ -0,0 +1,64 @@
+# Spec phase
+
+The spec phase ends when the human approves `difyctl/<app-slug>/spec.md`. Don't plan before that.
+
+## How to run the spec talk
+
+1. Start from intent: what the app is for, who uses it, what a good result looks like. Ask one question at a time, with choices where you can.
+2. Choose the mode early and say why. Workflow: one run, inputs to outputs. Chatflow: a conversation with memory.
+3. As you talk, keep two things:
+ - **Requirements.** Each condition or feature the human states becomes `R<n>`, in their words, typed `feature` (something the app does), `rule` (a condition or limit) or `failure` (what happens when something goes wrong).
+ - **Process graph.** A Mermaid graph of business steps, not nodes.
+4. Walk 3 to 6 realistic cases through the graph with the human. Include edge cases: empty input, a tool failing, an answer too long.
+5. Collect resources: models, tools and plugins, knowledge bases, credentials.
+ - For each step that calls an outside service or needs a model, search first: `difyctl get tool --query <service>`, `difyctl get model --model-type llm`, `difyctl get knowledge_base --query <words>`, then `difyctl get marketplace plugin --query <service>`.
+ - Show the human a short list per step, ranked by the tool rule in `build-workflow.md`: name, brief, publisher type, install count, installed and configured or not.
+ - If the best option needs something from the human (an API key, an install, a knowledge base to upload), ask for it.
+ - Record the human's choice and the options shown. Write an unknown item as open; never guess a name.
+6. Before you ask for approval, read the requirements back and ask "anything missing?". Each requirement needs a graph step and at least one acceptance case. Raise any gap with the human.
+7. Write the spec, check it against itself, and ask the human to review it.
+
+Acceptance check types: `exact` (the output must match), `contains` (given text or a pattern), `judged` (you grade against the case's rubric and show your reasoning).
+
+## Template
+
+Copy this into `spec.md` and fill it in.
+
+````markdown
+# <App name>: spec
+
+## Goal
+
+<What it does, for whom, what success looks like.>
+
+## Mode
+
+<Workflow or Chatflow>, because <why>.
+
+## Requirements
+
+- R1 (feature): Reply in the language the customer wrote in. Step: Answer.
+
+## Inputs and outputs
+
+- <name>: <type>, <required or optional>, e.g. <example>.
+
+## Process
+
+```mermaid
+flowchart LR
+ A[Read the question] --> B[Find the answer] --> C[Reply]
+```
+
+## Acceptance cases
+
+- A1: Customer asks in French. Inputs: query "Où est ma commande ?". Expected: French, gives the status. Check: judged, French and under 80 words. Covers R1.
+
+## Resources
+
+- <need>: <choice>. Shown: <options>. <confirmed or open>, provided by <who>.
+
+## Out of scope and open questions
+
+- <item>
+````
diff --git a/skills/difyctl/references/operations.md b/skills/difyctl/references/operations.md
new file mode 100644
index 00000000000..340079f2d8e
--- /dev/null
+++ b/skills/difyctl/references/operations.md
@@ -0,0 +1,25 @@
+# Running operations
+
+`difyctl run console_app workflow --app-id <id> --inputs '{"a":1}'`. Each top-level field of `input` is a flag, dashes for underscores. Scalars take a value; objects, maps and lists of objects take a JSON literal or `@file.json`; lists of scalars repeat the flag. Fields named `input`, `stream`, `only`, `output`, `verbose`, `json` or `help` have no flag; pass them through `--input`.
+
+`--input '{"a":1}'`, `--input @file.json` or `--input @-` (stdin) sends the whole body; field flags merge over it. A dotted id is a command with the dots as spaces: `run.console_app.workflow` is `difyctl run console_app workflow`.
+
+Run an app with the op for its mode: `run console_app workflow`, `run console_app chat`, `run console_app advanced_chat`, `run console_app completion`. First `difyctl describe console_app --app-id <id> --json` and read `input_schema`; that is the shape of `inputs`. Local files go under `files`, keyed by the app's file variable name (`{"files":{"doc":"./r.pdf"}}` or a list of paths); files for the run itself under `attachments`; URLs straight into `inputs`.
+
+## difyctl-only flags
+
+`--stream` prints each event of a streaming op as one JSON line instead of folding them. `--only <event>` filters streamed events (repeatable). `--output <path>` saves a file-kind response; the default is the current directory under the server's filename, or `<op-id>.<ext>`. The default never replaces an existing file: it exits 2, and you pass `--output` to choose the path (an `--output` path is replaced). `--verbose` adds the raw server response to errors. A flag the operation's kind does not support exits 2.
+
+## Reading results
+
+Streaming ops fold to `{status, text, outputs?, total_tokens?, message_id?, conversation_id?, run_id?, error?, hints}`. `text.answer` is the reply; `text.by_source` appears only while `status` is `incomplete`. `status` is `ended`, `failed` (exit 1), `suspended` (a form is waiting; follow `hints`) or `incomplete` (stream broke early; exit 0, so check `status`). Any response may carry `hints: [{summary, op, input, form?}]`, the server's next steps: next page, confirm step, reply op, form submit. Errors can carry them too, at `error.server.hints`. Fill any `null` in `input` and pass it back with `difyctl <op, dots as spaces> --input '<input>'`.
+
+After `submit.run.form`, run its `get.run.event` hint to follow the run; repeat if it suspends again.
+
+## Errors and exit codes
+
+Stderr envelope: `{"error":{"code","message","hint"?,"details"?,"schema"?,"http_status"?,"server"?}}`. `code` is difyctl's (`server_error` for server rejections); the server's code is `error.server.code` (e.g. `dsl_invalid`). `details`: `[{loc,msg}]`.
+
+Exit: 2 bad input caught locally (incl. near-miss command); 1 server rejection or other failure; 4 not logged in (incl. unknown word while logged out), 401, 403 (a domain `error.server.code` such as `webapp_public_access_disabled`, `service_api_disabled` or `plugin_install_forbidden` is not a login problem: read the code and its hint); 6 catalog unavailable or `unknown_op`; 7 rate limited.
+
+PowerShell: use `--input @file.json`, and `$env:VAR='v'; difyctl ...`.
diff --git a/skills/difyctl/references/plugins.md b/skills/difyctl/references/plugins.md
new file mode 100644
index 00000000000..8682c226eb0
--- /dev/null
+++ b/skills/difyctl/references/plugins.md
@@ -0,0 +1,38 @@
+# Plugins, models and credentials
+
+## Find tools, models and knowledge bases
+
+1. `difyctl get tool --query <service>` lists tools the workspace can use: built-in and plugin tools, workflows published as tools, API tools and MCP tools. Each row has `configured` and a ready `node_data`.
+2. `difyctl get model --model-type llm` lists models across providers (`--provider <id>` for one). Use one whose `status` is `active`. Paste the row's `node_model` as the LLM node's `model` block; don't build it by hand.
+3. For knowledge bases: `difyctl get knowledge_base --query <words>`. A knowledge-retrieval node needs a row's `node_data`.
+4. Nothing fits: `difyctl get marketplace plugin --query <service> --category tool` (or `--category model`).
+5. When building an app, rank the options by the tool rule in [build-workflow.md](build-workflow.md).
+
+## Missing plugins after an import
+
+1. `difyctl check console_app dependency --app-id <app_id>` lists what the app needs and lacks. Its hint is a ready `install.plugin` call with every missing marketplace plugin.
+2. Plugins from GitHub or a package file can't be installed with difyctl. Tell the human to install them in the console.
+
+## Find and install
+
+1. `difyctl get marketplace plugin --query <words>` searches the marketplace. Each hit has `identifier` (the versioned id to install) and `installed`.
+2. Confirm with the human before installing. Then `difyctl install plugin --identifiers <identifier>`.
+3. Install finishes in the background. Run the `describe.plugin.task` hint until `status` is `success` or `failed`. On `failed`, show the human each plugin's `message`. If `all_installed` is true there is no task; follow the provider hint.
+4. On success the hint names the provider to set up: `describe.model_provider` or `describe.tool_provider`.
+
+`get.plugin` lists installed plugins; `provides` gives their provider ids.
+
+## Credentials
+
+1. `difyctl describe model_provider --provider <id>` (or `describe tool_provider`) shows `credential_form` and the saved `credentials` (names only).
+2. Ask the human for each form value. Never invent one, never print it, never write it into the working folder.
+3. Pass the values on stdin: `difyctl create model_provider credential --provider <id> --credentials @-` (for tools, `difyctl create tool_provider credential --provider <id> --credentials @-`), then write the JSON object to stdin.
+4. Rejected (model 422, tool 400): nothing saved; show the message, ask again.
+5. Model providers only: if a credential is already active, the hint offers `set` to replace it. `active: false` with no hint means the model has saved credentials but none in use: ask the human to pick one in the console.
+6. A tool provider whose `credential_types` lacks `api-key` uses OAuth. Ask the human to authorize it in the console.
+
+Self-hosted or OpenAI-compatible models: `create model credential` with `--provider <id>`, `--model`, `--model-type` and `--credentials @-`.
+
+## Remove
+
+Only when the human asks: `delete.plugin`. Removing a plugin breaks apps that use it; say so first. Uninstalling also deletes the plugin's saved credentials.
diff --git a/skills/difyctl/references/setup.md b/skills/difyctl/references/setup.md
new file mode 100644
index 00000000000..5290715fbec
--- /dev/null
+++ b/skills/difyctl/references/setup.md
@@ -0,0 +1,37 @@
+# Login and environment
+
+## Log in
+
+`login` uses the device flow: it prints a URL and a code, the human approves in a browser, and difyctl stores a token. One login at a time. A new login replaces the old one, and it replaces the code the human is looking at.
+
+**Check first.** Run `difyctl login --resume`. If it prints an `email`, you are logged in: skip login. If it fails with `not_logged_in`, log in.
+
+**Server.** Always pass `--server <url>`; `login` fails with `usage_missing_arg` without it. If the human has not named a server, ask which one. Never guess one.
+
+Log in only this way:
+
+1. `difyctl login --server <url> --no-browser --no-wait`. It saves a pending login and prints `verification_uri`, `user_code` and `expires_in` (seconds), then exits.
+2. Give the human the URL and the code. Ask them to reply when they have approved. Then end your turn. Do not poll, do not sleep, and do not start a background job.
+3. When the human replies, run `difyctl login --resume` once. If it prints the account `email`, you are logged in. If it prints `status: pending`, tell the human it is not approved yet and end your turn again.
+4. If the code expires or the human denies it, `--resume` fails. Start again from step 1.
+
+Never run `login` without `--no-wait`. It blocks until the human approves.
+
+A script that already has a token skips login: set `DIFY_SERVER` and `DIFY_TOKEN`. (v1's `DIFY_HOST` is not read.)
+
+`--no-browser` prints the URL instead of opening one; always pass it as an agent. `--insecure` skips TLS verification and allows `http://` (local dev only).
+
+## Sandboxes and machines without a keyring
+
+The token goes to the OS keyring by default. On Linux without a DBus session, difyctl uses a file instead, because the keyring there is lost when the session ends. In a sandbox, a container or a headless VM, the keyring can still be lost between sessions. There:
+
+- Add `--no-keyring` to `login`, so the token goes to a file. Pass it on the `--no-wait` call; `--resume` remembers it.
+- Leave `DIFY_CONFIG_DIR` unset unless the default folder is lost between sessions (macOS `~/.config/difyctl`, Linux `${XDG_CONFIG_HOME:-~/.config}/difyctl`, Windows `%APPDATA%\difyctl`). If you set it, put it on every command (`DIFY_CONFIG_DIR=<dir> difyctl ...`): an `export` does not carry over when each command runs in a new shell. The pending login from `--no-wait` lives there too, so `--resume` needs the same value. A `not_logged_in` error names the folder it checked.
+
+## Workspace
+
+`difyctl get workspace` lists your workspaces. `difyctl use workspace <id>` pins one on this device; later commands fill `workspace_id` from it. The pin is difyctl's own: it does not change the workspace open in the web console. `difyctl describe workspace` with no id shows the pinned workspace. `DIFY_WORKSPACE_ID` overrides the pin for one call.
+
+## Files
+
+`DIFY_CONFIG_DIR` holds login, tokens and catalog. `DIFY_CACHE_DIR` is unused.