CLI reference

Install the CLI, then run the synopkgland binary from your project directory.

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

Output	Meaning
Success	Exit status 0; commands with --json return {"ok":true,"command":"<name>","data":{}}, with command-specific data.
Failure	Exit status 1; JSON mode returns {"ok":false,"code":"<code>","message":"<message>","hint":"<hint>"}. Failed inspect also includes its report in data.
JSON availability	check, inspect, build, deploy, and status expose --json.
Project discovery	check, build, deploy, status, logs, and images pin search upwards from --project <dir> or the current directory. add uses that directory as the project root. inspect takes an SPK path directly.

deploy, status, and logs use --host to select the NAS. Environment variables already set in your shell take precedence over .env, found by searching upwards from the current directory; only the nearest file is loaded.

Connection setting	Lookup and result
--host <name>	Match hosts.<name> in ~/.synoagentcli/setting.json, then match a profile URL or its hostname.
Profile credentials	Use the profile URL and username / password, or auth.username / auth.password.
Environment credentials	If complete profile credentials are absent, use DSM_PASSWORD and DSM_USERNAME (default admin). The profile URL takes precedence; otherwise the supplied --host URL or hostname sets the address. A bare hostname becomes http://<host>:5000. DSM_URL is the address fallback when no host override is supplied.
Missing host	deploy and status raise HOST_REQUIRED; logs requires the option at argument parsing. deploy --dry-run needs no host.
Missing credentials	NAS_CREDENTIALS_MISSING; supply profile credentials or environment credentials. See errors.

global

synopkgland [options] [command]

Use synopkgland to create, validate, build, and deploy a DSM package.

Option	Description	Default
--project <dir>	Start project discovery at this directory; place it before the command. It does not apply to init.	Current directory
-h, --help	Show command help and exit.	—

check

synopkgland check [options]

Validate your manifest, capability combinations, API permissions, and Compose configuration.

Option	Description	Default
--json	Write the result envelope to stdout; progress and errors go to stderr.	Off
-h, --help	Show command help and exit.	—

inspect

synopkgland inspect [options] <spk>

Check any SPK without installing it, whether synopkgland built it or not. The output has two sections:

• DSM format, for every SPK: the archive layout, INFO, package.tgz, scripts, conf, icons and wizards, each finding with a stable SPK rule code.
• synopkgland contract, only for an SPK that synopkgland built (top-level sdk-package.json or native-layout.json, or synology-app.yaml in the payload): identity, payload, signature and administrator approval requirements. For a package that declares entry, it shows the mode and reports ENTRY_LAUNCHER_MISMATCH when the launcher does not match it. SPKs built by other tools are not held to this contract.

An error in either section exits with SPK_INSPECTION_FAILED and code 1; warnings alone exit 0. The --json report has synopkgland (whether the contract was checked), dsm (ok, errors, warnings) and the contract fields findings, payload, signed, capabilities, icon and entry.

Option	Description	Default
--json	Write the result envelope to stdout; on failure the report is in data.	Off
-h, --help	Show command help and exit.	—

images

synopkgland images [options] [command]

Select a container image command.

Option	Description	Default
-h, --help	Show command help and exit.	—

init

synopkgland init [options] [dir]

Create a project from the compose, binary, or native-go template.

Option	Description	Default
-t, --template <name>	Choose compose, binary, or native-go.	Required
--package <id>	Set the native package identifier.	Derived from directory name
--name <display>	Set the native display name.	Derived from directory name
--ui <vue|plain>	Choose the native-go UI; plain uses ui/app.js and ui/app.css.	vue for native-go
--with <caps>	Comma-separated native-go capabilities: files, jobs, login, root-ops, delegate.	None
--from <compose.yaml>	Import an existing Compose file; applies only to compose. package and displayname come from --package, --name or the directory name; install keeps only entries the file references.	Bundled example
--shared-folder <select|create>	Add a Shared Folder installation wizard; applies only to native-go.	None
--shared-folder-name <name>	Name the Shared Folder to create; required with create, omitted with select.	None
--shared-folder-key <key>	Set the Shared Folder configuration key.	shared
--shared-folder-permission <ro|rw>	Set the package account permission requested for the Shared Folder.	rw
--min-dsm <version>	Set the minimum DSM release or full version/build; see platforms.	Manifest value for build; template value for init
-h, --help	Show command help and exit.	—

Constraint	Behavior
Target directory	[dir] defaults to .. Colliding files fail with INIT_TARGET_NOT_EMPTY.
Native capabilities	--with applies only to native-go. login and delegate require --ui vue; delegate also enables jobs.
Delegate UI	Only the Vue panel can confirm the install-selected scope. init --ui plain --with delegate fails with CAPABILITY_COMBINATION_INVALID, and check refuses install-selected with a plain UI.
Template minimum DSM	Native-go and binary default to 7.1-42661; Compose defaults to 7.2.1-69057.

add

synopkgland add [options] <caps...>

Add files, jobs, login, root-ops, delegate, or portal to a native project.

Option	Description	Default
-h, --help	Show command help and exit.	—

Constraint	Behavior
Capability syntax	Pass names separated by spaces or commas. Already declared capabilities are reported as unchanged.
Project layout	Capability additions require backend.kind: go and backend.dir: backend.
File conflicts	Changed template files or symlinks fail with ADD_FILE_CONFLICT before capability files are written. Resolve the conflict and retry; see errors.
delegate	Adds jobs and the delegate declaration shown in the manifest reference. For ordinary-user access, set app.status to authenticated in backend/internal/api/permissions.json.
root-ops	Raises os_min_ver to 7.1-42661 when lower, and prints the change on stderr.
portal	Works with Go or binary backends. Needs root-ops or delegate, already declared or added in the same call; otherwise fails with STANDALONE_PORTAL_REQUIRES_EXECUTOR. Adds portal: {} and raises os_min_ver to 7.1-42661 when lower, printing the change on stderr. An existing portal is unchanged.

dev

synopkgland dev [options]

Start your Compose project locally and keep it running until you press Ctrl+C.

Option	Description	Default
-h, --help	Show command help and exit.	—

test

synopkgland test [options]

Validate your Compose project and wait for readiness; the containers stay running.

Option	Description	Default
-h, --help	Show command help and exit.	—

deploy

synopkgland deploy [options]

Build an SPK and install it on your NAS, or print a local deployment plan.

Option	Description	Default
--json	Write the result envelope to stdout; progress and errors go to stderr.	Off
--host <name>	Select a synoagentcli profile, URL, or hostname.	Required except for deploy --dry-run
--arch <family>	Build for one architecture; see the deployment limits below.	Detect from NAS when needed
--dev	Use a separate development package identity; Compose only.	Off
--share <slot=name>	Repeat to provide a Compose Shared Folder name for each slot.	Required on first deploy / saved answer
--run-as <slot=name>	Repeat to provide a Compose DSM user account for each slot; use a name, not a numeric UID or root.	Required on first deploy / saved answer
--param <NAME=value>	Repeat to provide declared Compose installation parameters. For native-go and binary, only the install wizard values of an install-selected delegate: delegate_share=<Shared Folder> or delegate_home=true.	Declared default when available; native first install of an install-selected delegate requires one
--dry-run	Print a local plan without connecting to a NAS, building, or installing.	Off
-h, --help	Show command help and exit.	—

Limit	Behavior
Native architecture	x86_64, aarch64, or armv7; one family, declared in arches. Without --arch, deployment detects the NAS CPU family.
Compose architecture	x86_64 or aarch64; a DSM-authenticated web App detects the NAS family when --arch is omitted.
Detection failure	Pass --arch for DEPLOY_ARCH_UNDETERMINED (native) or NATIVE_ARCH_UNDETERMINED (Compose gateway); see errors.
Native install options	--dev, --share and --run-as are unsupported. --param accepts only delegate_share or delegate_home for an install-selected delegate; the first install without one fails with DEPLOY_PARAM_REQUIRED before anything is built.
Native version	Increase version or build above the installed version; otherwise deployment fails with DEPLOY_VERSION_INVALID.
Native layout	Builds the SPK for the NAS architecture (an aarch64 NAS uses a declared armv8) and installs it. It takes no --param.
Administrator approval	Root operations and delegate need approval in the App window before they are ready.

status

synopkgland status [options]

Read the installed package status, launch URL, and capability readiness from DSM.

Option	Description	Default
--json	Write the result envelope to stdout; progress and errors go to stderr.	Off
--host <name>	Select a synoagentcli profile, URL, or hostname.	Required
--dev	Use a separate development package identity; Compose only.	Off
-h, --help	Show command help and exit.	—

Limit	Behavior
--dev	Compose only; native-go and binary reject it.
Capability states	ready, needs-admin-approval, unsupported, or blocked; an uninstalled package has blocked capabilities.
portal	Listed when the app declares portal. ready with the URL when an administrator applied an alias, needs-admin-approval when none is applied, and blocked before install or when the status cannot be read.
Root readiness	Compares DSM root tasks with the local dist/ SPK of the installed version. Without that SPK, it compares them with the source policy and the policy digest the running executor reports; executor bytes are not compared.
Native layout	Reports the installed state and the Open URL; a native layout has no capabilities.
identity: standalone	The executor is read through a short-lived App session made from the administrator’s DSM session and logged out right after. That needs an https:// host; over http:// the capability is blocked and says so.

logs

synopkgland logs [options]

Print package status lines and redacted diagnostics from DSM.

Option	Description	Default
--host <name>	Select a synoagentcli profile, URL, or hostname.	Required
--dev	Use a separate development package identity; Compose only.	Off
-h, --help	Show command help and exit.	—

Limit	Behavior
Output	Package status lines and redacted diagnostics for Compose, native-go, and binary; application log streaming and follow mode are unavailable.
Missing installation	Fails with NOT_INSTALLED; deploy the package first. See errors.
Project types	Compose, native-go, and binary; --dev is Compose only. Native layout is unsupported.

skill

synopkgland skill [options] [command]

Select a bundled agent skill command.

Option	Description	Default
-h, --help	Show command help and exit.	—

build

synopkgland build [options]

Build SPK files from dsm-package.yaml or synology-app.yaml.

Option	Description	Default
--json	Write the result envelope to stdout; progress and errors go to stderr.	Off
-o, --output <path>	Write one SPK to this path; native and gateway builds require a single explicit --arch.	Generated filename
--out-dir <dir>	Set the output directory for native builds or multiple Compose gateway builds.	Native: dist/; Compose: project root
--arch <families>	Build a comma-separated architecture list. Repeat the option to add more, for example --arch x86_64 --arch aarch64; see the build limits below.	Manifest arches; Compose gateway: both families
--min-dsm <version>	Set the minimum DSM release or full version/build; see platforms.	Manifest value for build; template value for init
--jobs <n>	Build up to n architectures at the same time; see parallel builds.	1 (one after another)
--verify-reproducible [when]	Build again from a clean state and compare the SPKs; when is changed or always. See reproducible builds.	Off; changed when given without a value
-h, --help	Show command help and exit.	—

Project type	Accepted --arch values and output
Native-go	x86_64, aarch64, armv7; builds every manifest architecture when omitted.
Binary	x86_64, aarch64, armv7; builds every manifest architecture when omitted.
Native layout	x86_64, aarch64, armv8, armv7; uses the manifest layout and build hooks.
Compose gateway	x86_64, aarch64; builds both when omitted. Container Manager support is limited to those families.
Compose without gateway	Produces an architecture-independent SPK; the containers still require a supported NAS family.
Frontend dependencies	Install them before building: run npm ci in frontend/ when it has a lockfile. Build does not install dependencies.
Single output path	Native and gateway builds require one explicit --arch with -o; otherwise use --out-dir.

Parallel builds

--jobs <n> builds up to n architectures at the same time. The SPK files and their names are the same as with --jobs 1, byte for byte. Each architecture gets its own temporary folder, and with n above 1 every output line is prefixed with its architecture, for example [aarch64]. SPK files go to the output folder only after every architecture succeeds. If one fails, the error names the architecture and no SPK from this build is written.

--jobs works for native-go, binary and Compose gateway builds without changes. A native layout hook is your own code, so check it first: with --jobs above 1, layout.payload must contain {arch}, and the hook must not write to a folder that another architecture also uses. Use SYNOPKGLAND_WORK_DIR for scratch files, or keep per-architecture paths such as target/<rust target>/. See existing native products.

Reproducible builds

--verify-reproducible keeps the SPKs of this build as the first round and builds once more into a temporary folder. The second build first removes the paths listed in reproducible.clean and uses an empty Go build cache (GOCACHE). Each SPK pair must match byte for byte. If one differs, the command fails with BUILD_NOT_REPRODUCIBLE and lists the payload and metadata files that differ (files that record payload checksums, such as INFO, differ with them). The SPKs of the first round stay in the output folder either way.

To skip the check while nothing it depends on has changed, list those files in the manifest:

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

The dependency fingerprint is the SHA-256 of each inputs file, the CLI version, and for native layout the native.toolkits pins. Source edits and version bumps do not change it. After a passing check the CLI writes it to reproducible-fingerprint.json in the project; commit that file. With --verify-reproducible or --verify-reproducible changed, a later build skips the second round when the fingerprint is unchanged and the architectures were already checked. --verify-reproducible always never skips. Without inputs, the check always runs and records nothing. --json adds reproducible to data: skipped, identical, fingerprint, changed (the inputs that differ from the record) and one result per SPK with its two sha256 values and the differing payload and metadata files.

Example output when a payload file changes between builds:

已產生 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]

Show help with synopkgland help [command].

Option	Description	Default
--project <dir>	Start project discovery at this directory; place it before the command. It does not apply to init.	Current directory
-h, --help	Show command help and exit.	—

images pin

synopkgland images pin [options]

Resolve container image tags to digests and update your Compose project.

Option	Description	Default
--check	Report unpinned or stale images without changing files; findings fail the command.	Off
-h, --help	Show command help and exit.	—

Constraint	Behavior
Registry access	Uses anonymous registry requests; private image authentication is unavailable. Docker is not required for pinning.
Files changed	Rewrites service image values in compose.yaml.
Check failure	--check reports findings and fails with IMAGE_PIN_REQUIRED; see errors.

images help

synopkgland images [options] [command]

Show help for a container image command.

Option	Description	Default
-h, --help	Show command help and exit.	—

skill path

synopkgland skill path [options]

Print the absolute path to the bundled skill pack.

Option	Description	Default
-h, --help	Show command help and exit.	—

skill list

synopkgland skill list [options]

List the bundled skills.

Option	Description	Default
-h, --help	Show command help and exit.	—

skill show

synopkgland skill show [options] <id>

Print the skill identified by <id>.

Option	Description	Default
-h, --help	Show command help and exit.	—

skill help

synopkgland skill [options] [command]

Show help for a skill command.

Option	Description	Default
-h, --help	Show command help and exit.	—