@fugood/bricks-cli 2.26.0-beta.3 → 2.26.0-beta.31

package/README.md

@@ -170,9 +170,18 @@ bricks device list [-k keyword] [-j|--json]
 # Resolve a device name or ID
 bricks device resolve <query> [-l limit] [-j|--json]
 
-# Get device details
+# Get device details (incl. stored Lock, Activity Log and Local Sync settings)
 bricks device get <device-id> [-j|--json]
 
+# Update device settings (only the given settings change; other ENV variables are kept)
+bricks device update <device-id> [-n name] [-d description] [--tags a,b] [--dry-run] [-j|--json]
+bricks device update <device-id> [-e KEY=VALUE ...] [--env-json '{"KEY":"value"}'] [--unset-env KEY ...]
+bricks device update <device-id> [--[no-]activity-log] [--activity-log-filter filter] [--[no-]activity-log-screenshot]
+bricks device update <device-id> [--[no-]local-sync] [--local-sync-priority 0-9] [--[no-]local-sync-dynamic-latency] [--local-sync-latency-offset ms]
+bricks device update <device-id> --lock | --unlock
+# --lock / --unlock run alone. A locked device refuses other updates: unlock it first.
+# ENV changes reach the running app after `bricks device refresh <device-id>` (not automatic).
+
 # Bind a new device with passcode
 bricks device bind <passcode> [-n device-name]
 bricks device bind <passcode> [--dry-run] [-j|--json]
@@ -206,8 +215,8 @@ bricks app resolve <query> [-l limit] [-j|--json]
 # Get application details
 bricks app get <app-id> [-c|--composed] [-j|--json]
 
-# Update application
-bricks app update <app-id> [-n name] [-d description] [-c config-json] [-f config-file] [--validate]
+# Update application (`-t ''` clears the tags; a locked application refuses all changes until --unlock)
+bricks app update <app-id> [-n name] [-d description] [-t tags] [--lock|--unlock] [-c config-json] [-f config-file] [--validate]
 
 # Short edit application (requires valid shortIds from app config)
 bricks app short-edit <app-id> -l '[{"shortId":"<subspace-short-id>","path":"property.name","content":"value"}]'
@@ -215,16 +224,39 @@ bricks app short-edit <app-id> -l '[{"shortId":"<subspace-short-id>","path":"pro
 # Bind/unbind devices
 bricks app bind <app-id> [-b device-ids] [-u device-ids]
 bricks app bind <app-id> [-b device-ids] [-u device-ids] [--dry-run] [-j|--json]
+# Set the viewport of new or bound devices (JSON or a JSON file keyed by device ID).
+# Fields: x, y, width, height, rotate, type (rotate|scroll), rotateType (crop|fit|physical-rotate),
+# scrollType (crop|fit), maintainAspectRatio, forceDeviceRatio, mirrorHorizontal, mirrorVertical, content.
+# Fields not given keep the current viewport, else the root layout (full size at 0,0).
+# A bound device keeps its other settings (automation, cron tests, control toggles, env).
+bricks app bind <app-id> --viewport '{"<device-id>":{"x":0,"y":0,"width":960,"height":540,"rotate":90}}' [--dry-run] [-j|--json]
 
 # Trigger automation
-bricks app trigger <app-id> <test-id> [--play|--stop] [--setup-at-launch]
+bricks app trigger <app-id> <test-id> [--play|--stop] [--setup-at-launch] [-g match-group]
 
-# Preview a release without publishing
+# Application Control pages (Runtime Editor, Canvas Control, Device Control):
+# issue a page token and print the URL of each page (needs an OAuth login: `bricks auth login`);
+# --no-token prints the sign-in URLs only and works with any login
+bricks app control-page <app-id> -t <short-edit,canvas-control,device-control,device-control-create-only> [--token-name name] [--expires-in days] [-e KEY=VALUE] [--no-token] [--dry-run] [-j|--json]
+# The printed URL is <controller>/<page>.html?workspace_secret=…&application_id=…; set BRICKS_CONTROLLER_URL to override the controller origin.
+
+# Create a release (--dry-run checks it without publishing). A semver --version must be newer than every semver release in the cloud (see `bricks app versions <app-id> -j`); non-semver labels such as the default app name work as before.
 bricks app release <app-id> -c <config-path-or-json> [-n name] [--version version] [--changelogs text] [--dry-run] [-j|--json]
 
+# CTOR projects: a config-only push (update-app) is the normal last step after edits.
+bricks ctor push --auto-commit -y
+# Release (deploy-app) only when a new version is requested. The version (from --version, --auto-version or package.json) must be semver and newer than every cloud release; a duplicate or lower one is refused before anything changes. There is no bypass flag: restore an old release with `bricks app switch-version`.
+bricks ctor deploy --auto-commit --version <next-version> -y
+
+# List release versions, then switch the platform config to one (ID or name).
+# The local CTOR project is not changed. Unreleased changes are dropped: confirm, or pass -y.
+bricks app versions <app-id> [-j|--json]
+bricks app switch-version <app-id> <version-id-or-name> [-y|--yes] [--dry-run] [-j|--json]
+
 # Diagnose a config: schema validation + semantic lint rules
 # (data-update-race, redundant-rect-overlay, off-grid-frame, out-of-bounds-frame,
-#  wait-async-no-op, missing-result-param, unused-data-node, z-order-cover)
+#  wait-async-no-op, missing-result-param, unused-data-node, z-order-cover,
+#  expression-global-variable, mapping-outside-items)
 # Accepts a local file path or a remote application id.
 bricks app doctor <app-id-or-path> [-c|--composed] [--strict] [--only codes] [--ignore codes] [-j|--json]
 ```
@@ -278,6 +310,32 @@ bricks group refresh <group-id> [--dry-run] [-j|--json]
 bricks group monitor <group-id> [-i interval-seconds]
 ```
 
+### Blueprints
+
+A Blueprint is a workspace-level map of a site: its applications, modules, devices, Data Bank
+properties and Media Flow boxes as nodes, with role cards and the edges between them. The CLI
+reads Blueprints; edit them in CTOR. These commands need the `query_blueprint` token permission.
+
+```bash
+# List blueprints (name, node count, revision, Orchestrator run state)
+bricks blueprint list [-k keyword] [-j|--json]
+
+# Resolve a blueprint name or ID
+bricks blueprint resolve <query> [-l limit] [-j|--json]
+
+# Get blueprint details (overview, counts, run state, referenced entities with no node)
+bricks blueprint get <blueprint-id> [-j|--json]
+
+# Nodes with authored edges and edges derived from the workspace (bindings, used modules, ...)
+bricks blueprint graph <blueprint-id> [-j|--json]
+
+# Nodes grouped by kind; removed or moved entities are flagged as missing
+bricks blueprint members <blueprint-id> [-j|--json]
+
+# Print the projection text that the Blueprint Orchestrator gets as its context
+bricks blueprint projection <blueprint-id>
+```
+
 ### Media Flow
 
 Media Flow commands require:
@@ -345,6 +403,9 @@ Notes:
 - When no `-v/--value-file` is given, `set` keeps the current value (useful to change only tags or the definition).
 - `-v` parses the input as JSON and falls back to a plain string (`-v '{"a":1}'` → object, `-v hello` → string).
 - Revoking the auto-provisioned `manager` / `used-by-device` keys rotates them instead of deleting them.
+- Space key values come back masked (last 4 characters) unless the login may read them: the
+  workspace owner, a role with `update-workspace`, or a token with the `manage_devtools` scope.
+  A key the login creates is always returned in full, and a masked key revokes by its full value.
 - The Data Bank endpoint is derived from the configured BRICKS endpoint
   (prod → `bank.bricks.tools`, beta → `bank-beta.bricks.tools`, dev → `localhost:8080`).
 - Environment overrides for CI / custom setups: `BRICKS_BANK_SPACENAME` + `BRICKS_BANK_SPACEKEY`
@@ -353,6 +414,16 @@ Notes:
   it in the buttress `state.json`, so that server's local functions can use `context.bank`
   (`--revoke` removes it; re-running rotates the key).
 
+### Buttress binding and device authentication
+
+`bricks buttress bind` pairs the server with the current workspace **and automatically
+provisions a workspace-scoped DevTools token** in its permission-restricted `state.json`.
+After restarting Buttress, agents with `local_devices = true` use it for matching-workspace
+devices without passing credentials through model arguments. Normal bind/status output
+hides the token; `--print` emits the complete secret state for remote provisioning.
+Rebind and restart to renew an expired token (default lifetime: 30 days). Rebinding does
+not revoke older tokens. Automatic device authentication assumes a trusted LAN.
+
 ### Interactive Mode
 
 ```bash