Pecofence CLI

pecofence-cli

pecofence-cli drives the PecoFence app already running on the user's Windows desktop. Every command prints JSON (except log). pecofence-cli <command> --help shows the flags with an example; pecofence-cli describe is the full catalog and describe --schema FenceDto|Settings|Cond the exact shapes. This file is enough to start; open describe only for something not covered here. Not for: installing PecoFence, editing its config.json (the app owns it), or files outside the desktop and portal folders.

Five rules

1. Snapshot first. Before bulk changes run snapshot save before-<task>, keep .snapshot.id and tell the user pecofence-cli snapshot restore <id> undoes the layout. Snapshots hold layouts only (fences, geometry, membership), never settings, rules or files.
2. Portals are real folders. A fence with "kind": "portal" shows a folder on disk; item move into or out of it moves the real files (undo only via Explorer). Run such a move with --dry-run first and show the user the fileMove entries and their destination. Pair --glob with --from.
3. Address by id. After fence list, use ids (or a unique prefix of 6+ hex digits), not titles. The desktop fence is always inbox, whatever its localised title (Desktop, 桌面, ...).
4. Ask for less. --fields id,title,rect,fit keeps only those keys (dotted paths, lists element-wise); a full fence is ~700 bytes. If your reader decodes stdout with a legacy code page (Python without encoding="utf-8" on a CJK system, Windows PowerShell 5), add --ascii.
5. Exit codes. 0 ok. 1 the app refused, or part of a batch failed: stderr has {"error": {"code", "message", "hint", "details"}}, follow hint. 2 usage. 3 not running: ask the user to start PecoFence; never fall back to editing files. 4 timeout: a PecoFence menu or dialog is open, ask the user to close it, then check fence list before retrying (it may have run).

Start

pecofence-cli status                                        # exit 3 = not running
pecofence-cli fence list --fields id,title,kind,tabHost,rect,fit,portal
pecofence-cli item list --fence inbox --fields id,fileName,kind,ext,modified,shortcutTarget,shortcutArguments
pecofence-cli monitor list                                  # workArea of each monitor, for placement

Not on PATH (portable ZIP)? Call the exe by its full path, e.g. %LOCALAPPDATA%\Programs\PecoFence\pecofence-cli.exe.

Items carry kind (folders, programs, installers, shortcuts, documents, images, music, video, archives, namespace, other), ext, size, modified / created (Unix seconds), openCount, lastOpened, shortcutTarget, shortcutArguments, path and assignedBy. Sort by these; open a file only when name and kind say nothing. Two shortcuts are duplicates only when target and arguments match.

Reading replies

• Mutations return {"changed": bool, ...} plus the affected object; changed: false means it was already so. A warning next to a success means something secondary failed or was skipped: report it.
• snapshotId appears when the app took a snapshot on its own first: fence delete of a fence with items, rule apply that moves items, item move of 20+ desktop items, snapshot restore.
• Coordinates are physical px in virtual-screen space (monitors left of the primary have negative x). A tab (tabHost set) reports its host window's rect; skip tabs when checking overlaps.
• fit: {columns, rows, fittingHeight, overflow}: overflow: true means the fence scrolls. When the app changes a rect on its own (auto height, whole-row snapping, size limits) the reply carries adjusted: {requested, applied, reason}: continue from applied.