CLI 參考

安裝 CLI，然後在你的專案目錄執行 synopkgland。

npm install -g @synopackageland/cli --registry=https://registry.npmjs.org
synopkgland --project ./my-app check --json

輸出	意義
成功	結束狀態為 0；提供 --json 的指令會回傳 {"ok":true,"command":"<name>","data":{}}，data 內容依指令而異。
失敗	結束狀態為 1；JSON 模式會回傳 {"ok":false,"code":"<code>","message":"<message>","hint":"<hint>"}。inspect 失敗時也會在 data 提供檢查報告。
JSON 選項	check、inspect、build、deploy 與 status 提供 --json。
專案搜尋	check、build、deploy、status、logs 與 images pin 會從 --project <dir> 或目前目錄往上搜尋。add 直接使用該目錄作為專案根目錄。inspect 直接接受 SPK 路徑。

deploy、status 與 logs 使用 --host 選擇 NAS。CLI 會從目前目錄往上搜尋 .env，只載入最近的一個檔案，且不會覆寫 shell 已設定的環境變數。

連線設定	搜尋順序與結果
--host <name>	先比對 ~/.synoagentcli/setting.json 的 hosts.<name>，再比對 profile 的 URL 或主機名稱。
Profile 憑證	使用 profile 的 URL 與 username／password，或 auth.username／auth.password。
環境變數憑證	Profile 未提供完整憑證時，使用 DSM_PASSWORD 與 DSM_USERNAME（預設為 admin）。優先使用 profile URL，否則使用 --host 指定的 URL 或主機名稱。單純的主機名稱會轉為 http://<host>:5000。未提供主機覆寫值時，才以 DSM_URL 作為後備位址。
未指定主機	deploy 與 status 會回報 HOST_REQUIRED；logs 在解析參數時就要求此選項。deploy --dry-run 不需要主機。
缺少憑證	回報 NAS_CREDENTIALS_MISSING；請提供 profile 憑證或環境變數憑證。參閱錯誤碼。

global

synopkgland [options] [command]

使用 synopkgland 建立、驗證、建置與部署 DSM 套件。

選項	說明	預設值
--project <dir>	從此目錄開始搜尋專案；放在指令之前。此選項不適用於 init。	目前目錄
-h, --help	顯示指令說明並結束。	—

check

synopkgland check [options]

驗證你的 manifest、能力組合、API 權限與 Compose 設定。

選項	說明	預設值
--json	將結果物件寫入 stdout；進度與錯誤寫入 stderr。	關閉
-h, --help	顯示指令說明並結束。	—

inspect

synopkgland inspect [options] <spk>

不執行安裝，檢查任何 SPK，不限 synopkgland 建置的套件。輸出分兩個區段：

• DSM 格式：所有 SPK 都檢查。讀取封存結構、INFO、package.tgz、scripts、conf、圖示與精靈，每個問題都附固定的 SPK 規則碼。
• synopkgland 合約：只檢查 synopkgland 建置的 SPK（最上層有 sdk-package.json 或 native-layout.json，或 payload 有 synology-app.yaml），包括識別資訊、內容、簽章與管理員核准需求。套件宣告了 entry 時，會顯示該模式；啟動圖示設定與它不符時回報 ENTRY_LAUNCHER_MISMATCH。其他工具建置的 SPK 不受這份合約約束。

任一區段有錯誤時以 SPK_INSPECTION_FAILED 與結束碼 1 結束；只有警告時結束碼為 0。--json 報告有 synopkgland（是否檢查了合約）、dsm（ok、errors、warnings），以及合約欄位 findings、payload、signed、capabilities、icon 與 entry。

選項	說明	預設值
--json	將結果物件寫入 stdout；失敗時報告在 data。	關閉
-h, --help	顯示指令說明並結束。	—

images

synopkgland images [options] [command]

選擇容器映像指令。

選項	說明	預設值
-h, --help	顯示指令說明並結束。	—

init

synopkgland init [options] [dir]

使用 compose、binary 或 native-go 模板建立專案。

選項	說明	預設值
-t, --template <name>	選擇 compose、binary 或 native-go。	必填
--package <id>	設定原生套件識別名稱。	由目錄名稱產生
--name <display>	設定原生套件顯示名稱。	由目錄名稱產生
--ui <vue|plain>	選擇 native-go UI；plain 使用 ui/app.js 與 ui/app.css。	native-go 使用 vue
--with <caps>	以逗號分隔 native-go 能力：files、jobs、login、root-ops、delegate。	無
--from <compose.yaml>	匯入現有的 Compose 檔案；僅適用於 compose。package 與 displayname 取自 --package、--name 或目錄名稱；install 只保留檔案有引用的項目。	內建範例
--shared-folder <select|create>	加入共用資料夾安裝精靈；僅適用於 native-go。	無
--shared-folder-name <name>	設定要建立的共用資料夾名稱；create 時必填，select 時省略。	無
--shared-folder-key <key>	設定共用資料夾的設定鍵。	shared
--shared-folder-permission <ro|rw>	設定共用資料夾所需的套件帳號權限。	rw
--min-dsm <version>	設定最低 DSM 版本或完整版本／組建編號；參閱平台。	build 使用 manifest 值；init 使用模板值
-h, --help	顯示指令說明並結束。	—

限制	行為
目標目錄	[dir] 預設為 .。檔案衝突時回報 INIT_TARGET_NOT_EMPTY。
原生能力	--with 僅適用於 native-go。login 與 delegate 需要 --ui vue；delegate 也會啟用 jobs。
Delegate UI	只有 Vue 面板能確認 install-selected scope。init --ui plain --with delegate 會以 CAPABILITY_COMBINATION_INVALID 失敗，check 也會拒絕 plain UI 搭配 install-selected。
模板最低 DSM	Native-go 與 binary 預設為 7.1-42661；Compose 預設為 7.2.1-69057。

add

synopkgland add [options] <caps...>

在原生專案加入 files、jobs、login、root-ops、delegate 或 portal。

選項	說明	預設值
-h, --help	顯示指令說明並結束。	—

限制	行為
能力語法	名稱可用空白或逗號分隔。已宣告的能力會回報為未變更。
專案配置	加入能力需要 backend.kind: go 與 backend.dir: backend。
檔案衝突	已修改的模板檔案或符號連結會在寫入能力檔案前回報 ADD_FILE_CONFLICT。處理衝突後重試；參閱錯誤碼。
delegate	加入 jobs，以及 manifest 參考所示的 delegate（委派）宣告。一般使用者需要存取時，請在 backend/internal/api/permissions.json 將 app.status 設為 authenticated。
root-ops	os_min_ver 較低時提高至 7.1-42661，並在 stderr 印出此變更。
portal	適用於 Go 或 binary 後端。需要已宣告或在同一次呼叫加入 root-ops 或 delegate，否則以 STANDALONE_PORTAL_REQUIRES_EXECUTOR 失敗。加入 portal: {}，並在 os_min_ver 較低時提高至 7.1-42661，於 stderr 印出此變更。已有 portal 時不變更。

dev

synopkgland dev [options]

在本機啟動 Compose 專案，持續執行直到你按下 Ctrl+C。

選項	說明	預設值
-h, --help	顯示指令說明並結束。	—

test

synopkgland test [options]

驗證 Compose 專案並等待就緒；容器會繼續執行。

選項	說明	預設值
-h, --help	顯示指令說明並結束。	—

deploy

synopkgland deploy [options]

建置 SPK 並安裝到你的 NAS，或輸出本機部署計畫。

選項	說明	預設值
--json	將結果物件寫入 stdout；進度與錯誤寫入 stderr。	關閉
--host <name>	選擇 synoagentcli profile、URL 或主機名稱。	必填，deploy --dry-run 除外
--arch <family>	針對單一架構建置；參閱下方部署限制。	需要時從 NAS 偵測
--dev	使用獨立的開發套件識別名稱；僅適用於 Compose。	關閉
--share <slot=name>	可重複指定，為每個 Compose 槽提供共用資料夾名稱。	首次部署必填／已儲存的答案
--run-as <slot=name>	可重複指定，為每個 Compose 槽提供 DSM 使用者帳號；使用名稱，不接受數字 UID 或 root。	首次部署必填／已儲存的答案
--param <NAME=value>	可重複指定，提供已宣告的 Compose 安裝參數。native-go 與 binary 只接受 install-selected delegate 的安裝精靈值：delegate_share=<共用資料夾> 或 delegate_home=true。	有宣告時使用宣告的預設值；install-selected delegate 的原生首次安裝必須提供其中之一
--dry-run	輸出本機計畫，不連線 NAS、不建置、不安裝。	關閉
-h, --help	顯示指令說明並結束。	—

限制	行為
原生架構	x86_64、aarch64、armv7；單一架構，且必須已在 arches 宣告。省略 --arch 時，部署會偵測 NAS CPU 架構。
Compose 架構	x86_64 或 aarch64；透過 DSM 驗證的 web App 在省略 --arch 時會偵測 NAS 架構。
偵測失敗	遇到 DEPLOY_ARCH_UNDETERMINED（原生）或 NATIVE_ARCH_UNDETERMINED（Compose gateway）時，指定 --arch；參閱錯誤碼。
原生安裝選項	不支援 --dev、--share 與 --run-as。--param 只接受 install-selected delegate 的 delegate_share 或 delegate_home；首次安裝未提供時，會在建置前以 DEPLOY_PARAM_REQUIRED 失敗。
原生版本	將 version 或 build 提高至已安裝版本之上；否則部署會回報 DEPLOY_VERSION_INVALID。
Native layout	建置 NAS 架構的 SPK（aarch64 NAS 使用已宣告的 armv8）並安裝。不接受 --param。
管理員核准	root 操作與 delegate 需要在 App 視窗核准後才會就緒。

status

synopkgland status [options]

從 DSM 讀取已安裝套件的狀態、啟動 URL 與能力就緒狀態。

選項	說明	預設值
--json	將結果物件寫入 stdout；進度與錯誤寫入 stderr。	關閉
--host <name>	選擇 synoagentcli profile、URL 或主機名稱。	必填
--dev	使用獨立的開發套件識別名稱；僅適用於 Compose。	關閉
-h, --help	顯示指令說明並結束。	—

限制	行為
--dev	僅適用於 Compose；native-go 與 binary 會拒絕。
能力狀態	ready、needs-admin-approval、unsupported 或 blocked；未安裝套件的能力為 blocked。
portal	App 宣告 portal 時列出。管理員已套用別名時為 ready 並附網址；尚未套用時為 needs-admin-approval；安裝前或無法讀取狀態時為 blocked。
Root 就緒狀態	以已安裝版本在本機 dist/ 的 SPK 比對 DSM 的 root 工作。沒有該 SPK 時，改以原始碼的 policy 與執行中 executor 回報的 policy digest 比對，不比對 executor 二進位檔。
Native layout	回報安裝狀態與開啟 URL；native layout 沒有能力。
identity: standalone	以管理員的 DSM 工作階段建立短期 App 工作階段來讀取 executor，讀完立即登出。這需要 https:// 主機；使用 http:// 時能力為 blocked 並說明原因。

logs

synopkgland logs [options]

輸出 DSM 套件狀態行與遮罩後的診斷資訊。

選項	說明	預設值
--host <name>	選擇 synoagentcli profile、URL 或主機名稱。	必填
--dev	使用獨立的開發套件識別名稱；僅適用於 Compose。	關閉
-h, --help	顯示指令說明並結束。	—

限制	行為
輸出	Compose、native-go 與 binary 的套件狀態行與遮罩後的診斷資訊；不提供 App 日誌串流或 follow 模式。
尚未安裝	回報 NOT_INSTALLED；先部署套件。參閱錯誤碼。
專案類型	Compose、native-go 與 binary；--dev 僅適用於 Compose。不支援 native layout。

skill

synopkgland skill [options] [command]

選擇內建的 agent skill 指令。

選項	說明	預設值
-h, --help	顯示指令說明並結束。	—

build

synopkgland build [options]

從 dsm-package.yaml 或 synology-app.yaml 建置 SPK 檔案。

選項	說明	預設值
--json	將結果物件寫入 stdout；進度與錯誤寫入 stderr。	關閉
-o, --output <path>	將單一 SPK 寫入此路徑；原生與 gateway 建置需要明確指定單一 --arch。	自動產生檔名
--out-dir <dir>	設定原生建置或多架構 Compose gateway 建置的輸出目錄。	原生：dist/；Compose：專案根目錄
--arch <families>	建置以逗號分隔的架構清單。可重複指定以加入更多架構，例如 --arch x86_64 --arch aarch64；參閱下方建置限制。	manifest 架構；Compose gateway：兩種架構
--min-dsm <version>	設定最低 DSM 版本或完整版本／組建編號；參閱平台。	build 使用 manifest 值；init 使用模板值
--jobs <n>	最多同時建置 n 個架構；參閱並行建置。	1（依序建置）
--verify-reproducible [when]	從乾淨狀態再建置一次並比對 SPK；when 為 changed 或 always。參閱可重現建置。	關閉；不帶值時為 changed
-h, --help	顯示指令說明並結束。	—

專案類型	接受的 --arch 值與輸出
Native-go	x86_64、aarch64、armv7；省略時建置 manifest 的所有架構。
Binary	x86_64、aarch64、armv7；省略時建置 manifest 的所有架構。
Native layout	x86_64、aarch64、armv8、armv7；使用 manifest 的配置與建置 hooks。
Compose gateway	x86_64、aarch64；省略時建置兩種架構。Container Manager 僅支援這些架構。
未使用 gateway 的 Compose	產生不限定架構的 SPK；容器仍需要支援的 NAS 架構。
前端依賴套件	建置前先安裝：frontend/ 有 lockfile 時，在該目錄執行 npm ci。建置不會安裝依賴套件。
單一輸出路徑	原生與 gateway 建置使用 -o 時，需明確指定單一 --arch；否則使用 --out-dir。

並行建置

--jobs <n> 最多同時建置 n 個架構。產出的 SPK 檔案與檔名都和 --jobs 1 完全相同（逐位元組一致）。每個架構使用各自的暫存資料夾；n 大於 1 時，每行輸出前會加上架構，例如 [aarch64]。所有架構都成功後，SPK 才會寫入輸出資料夾。任一架構失敗時，錯誤訊息會標明架構，這次建置不會寫入任何 SPK。

native-go、binary 與 Compose gateway 建置可直接使用 --jobs。native layout 的 hook 是你自己的程式，請先確認：--jobs 大於 1 時，layout.payload 必須含 {arch}，hook 也不可寫入其他架構同時使用的資料夾。暫存檔請放在 SYNOPKGLAND_WORK_DIR，或維持依架構區分的路徑，例如 target/<rust target>/。參閱封裝既有的原生產品。

可重現建置

--verify-reproducible 把這次建置的 SPK 當作第一輪，再建置一次到暫存資料夾。第二次建置會先刪除 reproducible.clean 列出的路徑，並使用空的 Go 建置快取（GOCACHE）。每組 SPK 必須逐位元組相同；若有不同，指令以 BUILD_NOT_REPRODUCIBLE 失敗，並列出不同的 payload 與 metadata 檔案（INFO 這類記錄 payload checksum 的檔案會跟著不同）。無論結果如何，第一輪的 SPK 都留在輸出資料夾。

若要在依賴沒變時略過檢查，在 manifest 列出這些檔案：

reproducible:
  inputs: [backend/go.mod, backend/go.sum, frontend/package-lock.json]
  clean: [target/{arch}]

依賴指紋由每個 inputs 檔案的 SHA-256、CLI 版本，以及 native layout 的 native.toolkits pin 組成；修改原始碼或調升版本不會改變它。檢查通過後，CLI 會把指紋寫入專案的 reproducible-fingerprint.json，請 commit 這個檔案。使用 --verify-reproducible 或 --verify-reproducible changed 時，若指紋未變且這些架構已檢查過，之後的建置會略過第二輪。--verify-reproducible always 一律不略過。沒有 inputs 時每次都會檢查，也不記錄指紋。--json 會在 data 加上 reproducible：skipped、identical、fingerprint、changed（與紀錄不同的 inputs），以及每個 SPK 一筆結果，含兩個 sha256 值與不同的 payload、metadata 檔案。

payload 檔案在兩次建置間不同時的輸出範例：

已產生 dist/MyApp-1.0.0-0001-x86_64.spk
可重現檢查：MyApp-1.0.0-0001-x86_64.spk 不同（sha256 3f2a… ≠ 9c41…）
  payload ui/cgi/api.cgi
  metadata INFO

help

synopkgland [options] [command]

使用 synopkgland help [command] 顯示說明。

選項	說明	預設值
--project <dir>	從此目錄開始搜尋專案；放在指令之前。此選項不適用於 init。	目前目錄
-h, --help	顯示指令說明並結束。	—

images pin

synopkgland images pin [options]

將容器映像標籤解析為 digest，並更新你的 Compose 專案。

選項	說明	預設值
--check	回報未固定或過期的映像，不修改檔案；發現問題時指令會失敗。	關閉
-h, --help	顯示指令說明並結束。	—

限制	行為
Registry 存取	使用匿名 registry 請求；不提供私有映像驗證。固定映像不需要 Docker。
修改的檔案	改寫 compose.yaml 的 service image 值。
檢查失敗	--check 會回報發現的問題，並以 IMAGE_PIN_REQUIRED 結束；參閱錯誤碼。

images help

synopkgland images [options] [command]

顯示容器映像指令的說明。

選項	說明	預設值
-h, --help	顯示指令說明並結束。	—

skill path

synopkgland skill path [options]

輸出內建 skill pack 的絕對路徑。

選項	說明	預設值
-h, --help	顯示指令說明並結束。	—

skill list

synopkgland skill list [options]

列出內建 skills。

選項	說明	預設值
-h, --help	顯示指令說明並結束。	—

skill show

synopkgland skill show [options] <id>

輸出 <id> 指定的 skill。

選項	說明	預設值
-h, --help	顯示指令說明並結束。	—

skill help

synopkgland skill [options] [command]

顯示 skill 指令的說明。

選項	說明	預設值
-h, --help	顯示指令說明並結束。	—