trim-cli

trim-cli

CLI preparation

This Skill corresponds to the npm package @trimjs/trim-cli@0.1.1, requires Node.js 18+. Before first use, run trim-cli --version; if not installed or version mismatch, install the matching version:

npm install -g @trimjs/trim-cli@0.1.1

You can also replace trim-cli in the commands below with npx -y @trimjs/trim-cli@0.1.1, no global install needed. Installing the Skill does not automatically install the CLI, nor log in to the NAS. OAuth login requires an interactive terminal.

Command-line client for TRIM NAS / fnOS. Accesses system business interfaces and native app APIs via HTTP API proxy, covers authentication, files, albums, Baidu Netdisk, app center, Docker, downloads, logs, monitoring, network, power, storage, and user management.

Task routing

Choose the most specific entry first, then follow the reference or workflow in the entry:

Task	Entry
Login, session, connection failure, profile	`entries/trim-shared.md`、`reference/_index.md`
Files, finder, shared directories, ACL, upload/download	`entries/trim-file.md`、`reference/workflows/file-routing.md`
Album search, AI image search, details, preview	`entries/trim-photos.md`、`reference/workflows/photos-routing.md`
Baidu Netdisk authorization status, files, saving share links, transfer tasks, sync tasks	`entries/trim-baidu-netdisk.md`、`reference/baidu-netdisk.md`
App center, Docker, downloads, logs, monitoring	Corresponding `entries/` file and `reference/_index.md`
Storage write operations	`entries/trim-storage.md`、`reference/workflows/storage-dangerous-ops.md`
Users, user groups, permissions	`entries/trim-user.md`、`reference/user.md`
Real-device verification	`reference/workflows/device-validation.md`

Security rules

Video/Media APIs are currently not part of this skill; do not probe or call the media command that may exist in the CLI.
Login uses only OAuth 2.0 Authorization Code + PKCE; do not request, guess, or generate NAS usernames/passwords, 2FA, old tokens, or manual access-token login commands.
Fixed OAuth client_id=YJNMPJUGA9, request the trim.* scopes required by the current CLI per module; see the full list in reference/oauth.md. The authorization URL does not contain redirect_uri。
Production environment uses only interactive login: the CLI generates the authorization link and keeps waiting; the user logs in through the browser, confirms authorization, copies the one-time code, and pastes it into the CLI's Authorization code prompt. The Agent does not fill in account credentials, does not automatically click authorize, does not read the page code, and does not put the code into command parameters.
The session stores access/refresh tokens, expiration time, and OAuth device information; sensitive values only go into platform secure storage or an explicitly chosen file backend, and are not written to normal output or error logs.
Access tokens are automatically refreshed when nearing expiration;/ogh/ac/w or /ogh/ac/h/* upon receiving HTTP 401 will refresh and retry only once. On consecutive 401s or refresh failure, require a new OAuth login; do not loop, do not fall back to old login flows.
Before refresh, confirm that the current profile's session storage is writable; concurrent refreshes reuse the newer token already written.
If the saved session lacks the current module scope (including old file photo authorization), re-login is required; refresh cannot extend already-authorized scopes.
logout Clear the current profile's session and OAuth pending files; do not claim that server-side tokens have been revoked.
Remote plaintext HTTP requires explicit --allow-insecure-http; self-signed HTTPS uses --tls-insecure。
Agents or non-interactive flows must always explicitly pass --yeswhen executing write commands; high-risk storage commands also require the necessary password pre-validation.
Baidu account authorization can only be completed on the Baidu Netdisk app login page on the NAS; the CLI only checks status, and does not generate authorization links, nor receive Baidu account passwords or OAuth codes.
Do not send refresh tokens or authorization codes to unrelated third parties.

Connection options

--host <host>                 NAS 主机，默认 localhost
--port <port>                 端口，显式传入时优先
--profile <name>              独立 session profile
--scheme auto|http|https      传输协议，默认 auto
--allow-insecure-http         允许远程明文 HTTP
--tls-insecure                允许 HTTPS 自签证书

When connection parameters are not explicitly passed, the CLI reuses the host, port, scheme, and TLS settings saved in the current profile. By default, loopback is http://localhost:5666; remote IPs default to HTTPS 5667, and domain names default to HTTPS 443.

Minimal authentication flow

trim-cli --profile home --host <host> --port <port> --scheme https login
trim-cli --profile home login --refresh
trim-cli --profile home logout

login outputs the authorization link and attempts to open the browser, then waits in the current terminal for Authorization code. The user must complete the browser login and authorization themselves, then paste the one-time code shown on the page back into this prompt. If the browser cannot be opened automatically, use login --no-open; the authorization steps are still exactly the same.

Remote plaintext device example:

trim-cli --profile home --host <host> --port 5666 --scheme http --allow-insecure-http login --no-open

Common read-only commands

trim-cli --profile home system info
trim-cli --profile home file ls /vol1
trim-cli --profile home file ls-dir /vol1
trim-cli --profile home file usage 1
trim-cli --profile home photos folders
trim-cli --profile home photos search <keyword> --limit 20
trim-cli --profile home baidu-netdisk status
trim-cli --profile home baidu-netdisk ls /
trim-cli --profile home app list
trim-cli --profile home docker image ls
trim-cli --profile home download ls
trim-cli --profile home monitor cpu
trim-cli --profile home storage pools
trim-cli --profile home user info

Raw requests

When the system business lacks a named command, use raw; the Photos native HTTP API uses photos request。raw Only built-in, audited read-only endpoints may omit --yes; all other endpoints (including unknown endpoints) must first be confirmed and explicitly passed --yes. The command still validates the path and request body. For raw request results, you must check both the HTTP status and the business response code/final state; do not rely only on the process exit code.

Output conventions

Named commands output a JSON plan or business data by default. For Photos search, total is the total number of matches; AI image search can report an exact count only when the response provides a stable total; otherwise it can only report the number of items returned this time. Preview URLs usually still require logged-in browser cookies.

file ls-dir aggregates all directory segments into a JSON array;file usage aggregates capacity categories into a JSON array; for the same category identity, take the last result rather than accumulating.

About this skill