PCLI2
2.3.0 - 2026-09-23
Added
pcli2 apicalls any endpoint of the Physna API - pcli2 wraps some of the API's endpoints in commands;pcli2 api /tenants/{tenantId}/...reaches the others, with pcli2's login, token renewal, retries and tenant ({tenantId}is filled in).-Xsets the method,-F key=valueand-f key=valuebuild a JSON body,--inputreads one from a file or standard input, and--paginatemerges every page of a listing into one. Errors carry the server's message and the usual exit codes.folder geometric-match --groupsfinds groups of duplicates - Assets connected by a chain of matches form a group; each row getsGROUP_IDandGROUP_SIZEas the last two columns (groupId/groupSizein JSON). Ten copies of one part are one group instead of forty-five unrelated-looking rows. Without the flag the report is byte-for-byte unchanged.- Excel match reports carry a Summary sheet - After the matches: tenant, folders, threshold,
--exclusive, the time and the pcli2 version, then the number of pairs, the assets involved, the number of groups and a distribution of match percentages. A workbook forwarded to someone else used to carry no record of how it was produced. --format tableand--columns-tableprints aligned columns with a rule under the header, for every command that can print CSV.--columns path,uuidkeeps only the named CSV or table columns, in that order, matched by header name; an unknown name is an error (exit 64) that lists the available columns.--env/PCLI2_ENVchoose the environment for one command - Without changing the saved default (pcli2 env usedoes that), so scripts can work against staging and production at the same time. An unknown name is refused before anything runs (exit 67).PCLI2_TENANTsets--tenantfor one command, anduser list/user getaccept--tenant(they only ever used the active tenant).- Progress bars appear on their own in a terminal - For the commands that have
--progress, when stderr is a terminal (not in CI, not with--quietor--error-format json).--no-progressturns them off;--progressstill forces them on. - Shorter aliases -
gm,pm,vmandtmfor the geometric, part, visual and text match commands;env lsandenv rm.folder geometric-match --format xlsxis accepted as well asxls, andreport list --type/--statusaccept any letter case.
Fixed
-
asset downloadno longer fails on an assembly that has no dependency bundle - Physna serves an assembly as a ZIP of the assembly and its parts when it has one, or as the raw source file when it does not (for example an assembly in themissing-dependenciesstate). The command assumed every assembly was a ZIP, so a raw file was saved as<name>.zipand then rejected withZIP error: invalid Zip archive: Could not find EOCD. It now checks what actually arrived: a bundle is extracted next to the download and removed as before, and anything else is kept unchanged under the asset's own name (or the-opath). A bundle that is a ZIP but damaged still fails with the ZIP error. -
The credentials file can no longer be wiped by two pcli2 runs at once -
dev_credentials.jsonwas rewritten in place, and a file that could not be parsed was treated as empty. Two runs in parallel (xargs -P, cron, CI), one of them renewing its token, or a crash mid-write, could leave the file holding a single environment with an empty client ID and secret. It is now written to a temporary file and renamed into place, created owner-only (0600) from the start, and each change is a read-modify-write under a lock file, so parallel runs no longer lose each other's updates. A file that cannot be parsed is kept asdev_credentials.json.unreadable-<time>with a warning instead of being overwritten.config.ymland the update-check cache are written the same atomic way. -
pcli2 ... | headno longer exits 101 - A reader that stops early made pcli2 panic ("failed printing to stdout: Broken pipe") and exit 101, the network error code. A closed output pipe now ends the run quietly with exit 0. Any other internal panic is reported as one line (JSON under--error-format json) and exits 70. -
Token requests have timeouts and are retried - The login and renewal request went out on a client with no timeout at all, so an auth server that accepted the connection and never answered hung the run forever, and a single 503 from it failed the run. It now uses the same connect, read and total timeouts and the same retries with backoff as every other request.
-
asset metadata create-batchsurvives a failed token renewal - One failed renewal stopped the whole batch. Each call is now retried up to three times when authentication fails (the rule folder matches already follow); a credential that is really revoked still stops the run. -
An upload is no longer resent after a gateway error - After a 502 or 504 the upload was sent again, found the asset the first attempt had created, and a file that uploaded fine was reported as "Asset already exists" (a report job could be created twice the same way). Requests that create something are now retried only on 408, 429 and 503, which say the server did not act on them. Searches and batch lookups, which only read, are still retried on every transient status.
-
A dropped connection during a download is retried - A reset while the file body was streaming failed the item at once. The download now starts again, up to the usual number of retries, and writes through a 1 MiB buffer.
-
auth loginchecks the credentials before saving them - A mistyped secret used to replace a working one even though the login then failed. -
An error on the request retried after a token renewal keeps its meaning - A 404 exited 102 instead of 67, and a 409 was no longer recognised as a conflict (which broke
folder uploadonto an existing folder in that situation). -
tenant listexits non-zero when it fails - The error was printed but the exit code was 0. -
A new value in the API no longer breaks a listing - A report status, report type, dependency status or failure kind that this build does not know reads as
unknown/UNKNOWNinstead of failingreport list,tenant failuresorasset dependencieswith a JSON error.report create --waitkeeps polling a status it does not know. -
Names from the server are checked before they become local paths -
asset downloadwithout-o, andfolder downloadwithout-o, use the asset's or folder's name as the file or directory name. A name that is not one plain path segment (an absolute path,.., a\on Windows) is now refused with a pointer to-o. -
asset list --recursivelists nested folders correctly - Below the top level it looked each subfolder up by a path missing its parents (B/Cinstead of/A/B/C), so a nested folder was reported missing, or a different top-level folder of the same name was listed instead. It now walks the subtree by folder ID.--folder-path / --recursivealso includes the assets stored directly at the root, which it used to leave out. -
folder downloadhandles assemblies likeasset download- It had its own copy of the assembly handling, without the 2.2.1 fix: an assembly without a dependency bundle failed with a ZIP error. Both commands now share one path. Bundles are extracted from disk instead of being read into memory, entries whose path would leave the download directory are skipped, and the assembly file is written last, so--resumenever takes a half-extracted bundle for a finished one. -
folder downloadnames the assets it does not download - Assets that were still indexing or had failed processing were dropped without a word and left out of the totals. Assemblies inmissing-dependenciesare now downloaded. The others are counted in the summary as "Not downloaded" and listed with their state. -
folder downloadandfolder thumbnailaccept the root ---folder-path /(or/Home) failed with "folder not found", although both commands meant to name the output directory after the tenant in that case. They now cover the whole tenant.folder thumbnailalso checks the folder name before using it as the output directory, and reports an empty folder as a warning rather than an error. -
folder getandfolder renameexplain the root ---folder-path /now says that the root has no folder record of its own (and, for rename, that the root cannot be renamed), instead of "folder not found". -
JSON reports are byte-identical from run to run - Asset metadata (in match reports,
asset list,asset inventory) and the health report's file types were written in a different key order on every run, although the folder match help promises identical output. Keys are now written in sorted order, and assets are processed in path order wherever a list is walked.asset countsalso breaks ties between file types with the same count by name. -
asset countsadds up - An asset in a state none of the counters covers (a state added to the API later) was counted in the total and nowhere else. It is now counted asotherin the JSON output and on an "Other state" line of the tree output when there are any. The CSV row is unchanged, so scripts that read it into fixed fields keep working. -
One very long value no longer loses a whole XLSX report - A metadata value over Excel's 32,767-character cell limit failed the workbook after the match had finished. It is now cut short and marked
…[truncated], with a warning; the CSV and JSON outputs keep the full value. -
Dependency quantities are reported - The
OCCURRENCEScolumn ofasset dependenciesandfolder dependencieswas always 1, and the tree said "(1 occurrences)" for every part: the count the API returns was dropped while the tree was built. A bolt used four times now says 4. An assembly whose data contains itself is expanded once instead of forever. -
A part-match score the API did not report is an empty cell - It was printed as
0or0.0, which reads as a 0% match. -
Text-match asset links with a UI URL ending in
/tenants- They came out as.../tenants/tenants/.... All comparison and asset links are now built in one place. -
PCLI2_FORMATworks for every command -tenant list,tenant get,tenant state,tenant failures,tenant metadata list|assets|coverage|missing,asset metadata inferenceandfolder part-matchread--formatthemselves and never looked at the variable. They now honour it like the rest (an explicit--formatstill wins), andPCLI2_FORMAT=xlsnow works forfolder geometric-matchas--format xlsdoes. -
tenant use --nameaccepts a tenant UUID - As--tenantdoes. A name the cached tenant list does not know is looked up again once before giving up, so a newly granted tenant no longer needs--refresh. -
Tree output no longer depends on ptree settings - The tree renderer used to read
~/.config/ptree.tomlandPTREE_*variables, so a user's settings could change what--format treeprinted. -
Paginated listings never loop, repeat or silently truncate - One rule now decides when to stop walking a listing: after the last page, at a repeated page number (with a warning), or at the page cap (with a warning that the result is incomplete). The folder tree, which every path lookup reads, had no guard against a repeated page; part search appended the same matches again; the report, metadata-field, missing-metadata and failure listings stopped at 1,000 pages without saying so;
user liststopped at 5,000 users without saying so. -
--limitno longer repeats or skips records -report list,tenant failures,tenant metadata assetsandtenant metadata missingshrank the page size on the last request to fit--limitwhile the page number kept counting in the old size.--limit 1500returned records 501-1000 twice and never 1001-1500. -
folder uploadandfolder thumbnailstop cleanly - Without--continue-on-errorthey returned on the first failure while the remaining uploads carried on in the background, printed no summary, and left the progress bar over the error. They now stop the remaining items, count them as "Not attempted", print the summary and then the failures, asfolder downloaddoes.folder uploadrefuses files that already exist (without--skip-existing) before uploading anything, naming all of them, instead of failing when their turn came.folder thumbnailwrites each image whole or not at all. -
asset metadata create-batchno longer reloads the folder tree for every row under a missing folder - A folder that does not exist is remembered for the rest of the run.
Changed
asset metadata create-batchis faster and never half-applies an unresolvable file - Every row's asset is looked up first (UUID rows a thousand per request instead of one request each), new fields are registered once, and the rows are then written four at a time (--concurrent, 1 to 10;--concurrent 1writes strictly in file order). A row that cannot be resolved now stops the batch before anything is written, instead of after the rows above it had been written. Messages, skips and exit codes are otherwise unchanged.- A table by default in a terminal - When stdout is a terminal and no format was asked for (no
--format, noPCLI2_FORMAT), commands that can print CSV show a table instead of one long line of JSON. Output that goes to a pipe or a file is JSON exactly as before, so scripts are unaffected;--format jsongives JSON in the terminal too. The streaming folder match reports keep their formats.env listnow lists environments in alphabetical order. - Exit codes - A request the server keeps answering with 429 or a 5xx after every retry exits 69 (temporary failure, try again later) instead of 102. A connection lost mid-download exits 101 (network) instead of 102.
asset dependency-diffandasset resolve-dependencyexit with the real cause (100 for an expired login, 101 for the network, ...) instead of always 67 when one of their input assets could not be resolved. - Folder bulk commands run four at a time by default -
folder download,folder upload,folder thumbnailand the three folder match commands default to--concurrent 4instead of 1 (the retry layer already backs off on rate limits).--concurrent 1restores the old pace. folder downloadandfolder thumbnailstart sooner on large trees - The subtree is taken from the folder tree (one request per thousand folders) and the folders' assets are listed eight at a time; they used to walk the tree one folder at a time with two requests per folder.- Dependencies - ptree is built without its default features, which removes seven of the nine
cargo auditwarnings (unmaintainedatty,ansi_term,yaml-rust, and the unsoundlexical-core).inquire0.9 andindicatif0.18 remove two more unmaintained crates. The OS-keychainkeyringcrate is only built with the newos-keyringfeature (--no-default-features --features os-keyring); the default build stores credentials in the file as before. Dependabot now proposes weekly updates againstdevelop. env addwarns about plainhttp://URLs - Credentials and tokens sent to such a URL are not encrypted; loopback addresses are exempt. The URL is still accepted.
Documentation
- A shorter README and a book organised by purpose - The README is down from 1,360 lines to about 200: what pcli2 is, the quick start, installation, logging in, and links. The command and alias reference moved to a Command Reference page, the folder transfer notes to a new "Downloading and Uploading Folders" guide, the pipeline examples to Scripting and Automation, and the upgrade notes to the Installation guide. The book's contents are grouped into Getting Started, Guides, Reference and Help. The site's stale, committed build output (
public/, last built for 0.2.8) is no longer tracked. - Examples you can copy - Every
pcli2 ...example in the README and the user guide, and every example in--help, is now parsed by a test against the command tree. That caughtpcli2 asset lsin the top-level help and several READMEasset listexamples, which need--folder-path; thejqexample now uses the real fieldfile_size, the NuShell examples convert metadata values (which are strings in JSON) before comparing them, and the metadata "export, edit, reimport" workflow builds theASSET_PATH,NAME,VALUEfilecreate-batchactually reads. - Examples in
--helpfor the most-used commands (asset get|create|list|download|geometric-match|text-match|dependencies,folder list,tenant use,report list); the banner shows only above the top-level help; global flags are listed under "Global Options"; help wraps to the terminal width. Examples use/Home/...paths (Physna's root) instead of/Root/.... - Logging in without exposing the secret -
auth loginreadsPCLI2_CLIENT_IDandPCLI2_CLIENT_SECRET; the documentation and the "not logged in" hints no longer put the secret on the command line, and the GitHub Actions examples pass it throughenv:. - New pages: Credentials and Security (the credentials file is plain text;
auth logoutremoves only the token), Proxies, Certificates and Timeouts, and Troubleshooting (by exit code). The quickstart selects a tenant right after logging in.metadata-inference.mdnow says what actually happens on a failure (the run stops at the first failed update).CONTRIBUTING.mdreplaces the documentation-deployment page, which described the wrong trigger. - The Dockerfile builds again - It used Rust 1.83, below the minimum 1.88, and did not account for the library and benchmark targets. The Docker instructions keep the container's configuration in its own directory.
Removed
- Obsolete top-level documents -
HOMEBREW_QUICKSTART.mdandHOMEBREW_TAP_SETUP.md(the Homebrew formula is published by the release workflow) andRELEASE_NOTES_v1.0.0.md(the CHANGELOG has it). - About 1,100 lines of unreachable code - Public functions and types that nothing in the CLI or the tests used, among them the unused metadata cache, an in-memory download method, the unused per-operation client variants and several tenant printers. The library/binary split had hidden them from the compiler's dead-code warnings.
- An unused folder-download function in the client library -
actions::assets::download_folderwas never reachable from the CLI (folder downloadhas its own implementation) and extracted archives into a predictable shared temporary directory.