Co Synology

co syno

Use complete NAS paths and the user's selected profile. Read --json results, including completeness and the one next_command; exit 1 may contain useful partial evidence or a pending operation. Do not equate missing monitoring coverage with health. Real-device acceptance of this candidate remains pending.

Use already authorized work as the scope. File writes and public sharing need user intent; do not introduce a second approval when that intent is already clear. Do not enable NAS transports, alter host-key trust, run service controls or bypass TLS to make an inspection pass.

Commands and parser parity

Every leaf accepts --nas NAME, --json, --non-interactive and --timeout SECONDS. Common flags work before groups or after leaves; conflicting repeated values are usage errors. Use actual --help for any leaf before guessing flags. The provider waiting budget defaults to 60 seconds, maximum 3600.

--last and -n alias --limit (default 20, range 1–1000). Legacy get, put, shares and share PATH alias download/upload/share list/share create, with the same options and safeguards. Numeric references always require their explicit frozen --listing ID; the old mutable last-list cache is ignored. No implicit interactive row resolution is used. Canonical full paths are preferable.

Read-only workflow

bashCopy code
co syno nas list --json
co syno --nas home status --json
co syno --nas home ls /home/docs --json
co syno --nas home search invoice --in /home/docs --type file --json
co syno --nas home share list --json

Bare co syno lists accessible shared folders. / is the share inventory, not the DSM system root. ls now defaults to name ascending; file size 0 means an empty file, while directory size is null. Search is names-only and requires explicit scope; patterns need --glob. Search waits for a finished snapshot and requests cleanup before publishing rows. Incomplete searches fail.

Follow the exact pagination command with unchanged parameters. Cursors and listing contexts expire after 15 minutes and bind the selected profile/account. A second process's listing never changes an earlier row token. Live directory and link pages are not snapshots and may change between requests.

Connection sources

Verified HTTPS proves File Station access and supplies hostname/client timing. SNMPv3 authPriv supplies system/disk/RAID/interface indicators. SSH supplies the actual enumerated service state. HTTPS login does not authorize configuring or enabling the optional transports. Missing sources remain unavailable; device health OIDs and service commands vary by DSM/model.

Profiles use the global configuration directory. Secrets use the OS keyring, or an explicitly selected POSIX private-file fallback. Legacy keys.env connections require verified login; do not copy credentials into argv. OTP is interactive-only and never saved. JSON never prompts. --password-stdin reads only a password, never an OTP or multi-field secret record.

login --monitoring FILE uses non-secret snmp/ssh configuration. The CLI reference documents its schema. SNMP keys are prompted or read from the explicit private --snmp-secrets-file; SSH requires a named key and known-host file. Do not enable services or enroll unknown host keys as a workaround.

Transfers and sharing

bashCopy code
co syno download /home/docs/report.pdf --to ./Downloads/ --dry-run --json
co syno upload ./report.pdf /home/docs --dry-run --json
co syno mkdir /home/docs/archive --parents --dry-run --json
co syno move /home/docs/report.pdf /home/docs/archive/final.pdf --dry-run --json
co syno share create /home/docs/archive/final.pdf --expires 2026-09-30 --yes --json
co syno share list --json
co syno share revoke LINK_ID --yes --json

Use an existing local destination directory or an exact filename with an existing parent. Missing trailing-slash directories fail. Upload requires an existing remote directory. Directory transfers require --recursive, preserve base names and empty directories, and need an explicit merge choice if the base target exists. Type conflicts always fail. There is no overwrite by default. --yes never implies overwrite. Copy/move never merge an existing directory tree.

Dry-run may load an existing saved session from the credential store, but never refreshes auth, prompts, persists caches/state or submits mutations. It is a preflight, not a reservation. It does not read a share password; password validation is deferred. Read every completed/skipped/failed/unstarted item after a partial transfer. Do not assume recursive work or uploads are atomic.

A known pending copy/move has an operation_id. Inspect that same task:

bashCopy code
co syno status --operation OPERATION_ID --wait --json

Status never submits another write. Exact renamed destinations can have recorded staging steps; continuation_required supplies the original command to resume. A submission without a returned task ID is submission_unknown; inspect remote paths rather than blindly retrying. NAS restart/task eviction is not proof of failure. Receipts block automatic replay of uncertain steps.

Sharing requires an explicit NAS-local date or no-expiry. Unattended create and revoke require --yes; a protected link password is at most 16 characters and is never truncated. Create returns its URL. Inventory hides URLs unless --show-url is requested. Revoke removes only the link, never the source file.

Output and exits

All leaves emit a schema-1 JSON envelope with provider, nas, command, ok, status, complete, data, error, and next_command. Human results go to stdout and tips to stderr. Use JSON for scripting.

Before reporting completion, verify the requested outcome, relevant post-write inventory, and all partial/unknown fields. Keep unavailable monitoring, local hash evidence, live device coverage and release readiness distinct. The core has no public delete, service control, package management or shared-root creation.