PCLI2
Releases
2.8.2 - 2026-10-29
Security
- Dependencies - zip 9.1 (with zstd 0.14.3), rust_xlsxwriter 0.101, rustls 0.23.46, rustls-webpki 0.103.16 and tokio 1.54.1, clearing RustSec advisories published since 2.8.1. The zip advisories concern its own extraction helpers, which pcli2 does not call:
asset downloadunpacks archives itself and already skipped entries that lead outside the download directory. No command's output changes.
Changed
- API specification snapshot - Refreshed for Physna's 1.0.40 specification. Asset upload now lists documents, 2D drawings, archives and more 3D formats among the accepted files; pcli2 leaves that check to the server, so those files upload as they are. Without the refresh the weekly specification check would fail.
2.8.1 - 2026-10-08
Changed
- API specification snapshot - Refreshed for Physna's 2026-10-08 changes (still labelled 1.0.39): a server-side text search export endpoint, a
totalExactpaging field, NIIN selection for Part Finder reports, and NSN candidate schemas no endpoint uses yet. pcli2 uses none of them; no command's behaviour changes. Without the refresh the weekly specification check would fail.
2.8.0 - 2026-10-08
Added
tenant failuresshows retries and newest-failure times - The JSON output addslastAttempt(when, by whom and in how big a batch) to a failure that failed again after a self-service retry, andmostRecentByKind, the time of the newest failure of each kind across the tenant. The CSV and table output are unchanged.- Asset limit warning - On a tenant with an asset limit,
tenant usageaddsassetLimitto its JSON output and warns on stderr once the tenant holds the share of its limit at which the web UI starts warning (85%).folder uploadandasset create-batchwarn before uploading files that would reach that point or go past the limit. The warning never stops a command, and tenants without a limit are not checked.
2.7.1 - 2026-10-05
Fixed
- Weekly API specification check - The check failed on 2026-10-05 because Physna's documentation server returned an empty page for longer than the check waited. Behind it, Physna had added optional fields to the recent-failures, tenant settings and volumetric match responses and reworded their descriptions. pcli2 does not use the new fields, and no behaviour changes. The snapshot is refreshed. The check now retries for up to ten minutes and reports an unavailable specification separately from a real API change.
Changed
- Dependencies - thiserror 2.0.21. No command's output changes.
2.7.0 - 2026-09-28
Added
- Catalog search -
pcli2 catalog list | geometric-match | part-match | visual-matchmatches an asset from your tenant against a catalog, such as a supplier catalog, that Physna has enabled for your account.--innames the catalog and can be left out when there is only one. It accepts only catalogs: another of your tenants (a staging copy, another company) is refused before anything is searched, and a match the server returns from outside the catalog is dropped. The CSV has the columns of the matchingassetcommand plusCATALOG; the comparison link opens both assets side by side.catalog listwarns and the match commands exit 68 when catalog search is not enabled. Existing commands are unchanged.
2.6.1 - 2026-09-28
Changed
config.ymlanddev_credentials.jsonlist environments in name order - They were written in a different order on every save, so a save that changed nothing still changed the file (noisy in a diff or a dotfiles repository). Both are now sorted and written the same way each time; files in any order still load.
Fixed
- Weekly API specification check - The check against Physna's live OpenAPI specification had failed for three weeks: Physna added a staff-only
isInternalflag to the current-user response (pcli2 does not use it; no behaviour changes), and its documentation server intermittently returned an empty page. The snapshot is refreshed, and the check now retries with cache-busting over about two and a half minutes.
2.6.0 - 2026-09-23
Added
- Folder descriptions -
pcli2 folder description get | set | clearshows, sets or removes a folder's description (the optional text of up to 255 characters the web app shows), by--folder-pathor--folder-uuid.getprints the text alone, so a script can read it;setdrops surrounding spaces; an empty or over-long description is refused with exit 64 before anything is sent.folder create --description TEXTgives a new folder one, and without the flag nothing changes.folder getandfolder listinclude a folder'sdescriptionin their JSON output when it has one; their CSV columns are unchanged.
2.5.0 - 2026-09-23
Changed
env usebrings back the tenant last used in that environment - Switching environments used to clear the tenant every time, even when re-selecting the active environment, so each switch had to be followed bytenant use. Each environment now keeps its own tenant: switching back to one makes its tenant active again (the message names it), and an environment where no tenant was selected yet still starts with none, so a tenant from another environment is never carried over.config.ymlis read and written with serde_norway - serde_yaml, which pcli2 used for its configuration file, is deprecated upstream. serde_norway is its maintained drop-in fork: the same files load, and a saved file is byte-for-byte what pcli2 wrote before (checked against real and hand-edited configurations; the format is now pinned by tests).
2.4.2 - 2026-09-23
Fixed
folder visual-match --exclusiveworks - It failed on every asset withHTTP 400 - Validation Failedand exited 69 without a report: the folder filter it sent the visual search endpoint lacked themetadatafield the API requires.
2.4.1 - 2026-09-23
Changed
- Dependencies, major versions - reqwest 0.13, zip 8, thiserror 2, base64 0.23, rand 0.10, keyring 4 (optional OS-keychain build) and criterion 0.8 (benchmarks). HTTPS still uses the operating system's TLS and certificate store (reqwest 0.13 would default to rustls; pcli2 keeps native TLS). zip no longer includes AES support: Physna never serves password-protected bundles, and it needs a newer Rust than pcli2's minimum. Downloads extract to the same files, and no command's output changes.
2.4.0 - 2026-09-23
Added
pcli2 tenant usagereports how much the tenant used Physna - Searches (by type), compares, downloads, uploads, reports (by type), distinct active users and per-feature counts over a period of UTC days, plus how many assets of each type the tenant holds. The last 30 days by default;--days,--fromand--tochoose another period of up to 366 days, and--dailyprints one row per day. CSV and table output have oneCATEGORY,NAME,COUNTrow per number, so a count Physna adds later is a new row rather than a new column. Needs the tenant admin role.
Changed
- Dependencies - clap 4.6.7, clap_complete 4.6.11, uuid 1.26.1, rust_xlsxwriter 0.99.1, dirs 7.0.0, ptree 0.5.2, clap_mangen 0.3.3 and strum 0.28.0. Configuration, cache and credential file locations are unchanged, and so is the output of every command. Dependabot now proposes minor and patch updates monthly, grouped into one pull request; major versions are upgraded by hand.
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.
2.2.0 - 2026-09-22
Added
-
asset moveputs an asset in another folder (aliasmv) ---uuidor--pathnames the asset,--folder-uuidor--folder-paththe destination;/(or/Home) as the path is the root. The asset keeps its UUID and metadata; only its path changes. Silent on success,--dry-runnames the asset and the destination. UsesPATCH /tenants/{tenantId}/assets/{assetId}/folder. -
asset resolve-dependencylinks a missing dependency to an existing asset (aliasresolve-dep) - An assembly whose referenced part was not found stays in themissing-dependenciesstate.--dependencytakes the missing path asasset dependencieslists it,--target-uuidor--target-paththe asset that should stand in for it; the server re-indexes the assembly. The dependency must be one of the assembly's missing ones, otherwise the command stops and lists them (exit 64), so a typo never reaches the server. Silent on success,--dry-runnames everything. UsesPOST /tenants/{tenantId}/assets/{assetId}/resolve-dependency. -
tenant metadatamanages the field registry - Besidelist:rename --name OLD --new-name NEW(values on assets are kept),delete --name NAME [--force](the server refuses a field still in use unless--force, which also removes its values from every asset; confirms unless--yes,--dry-runsupported),assets --name NAME [--limit N](the assets with a value for the field, printed likeasset list),coverage(how many assets carry any metadata: counts and a percentage, JSON or CSV), andmissing [--folder-path P]* [--extension E]* [--limit N](the assets with no metadata at all, oldest first; Physna's demo assets excluded). Fields are addressed by their exact registered name; an unknown name lists the registered ones (exit 67). Endpoints:PATCH/DELETE /tenants/{tenantId}/metadata-fields/{fieldId},GET .../metadata-fields/{fieldId}/assets,GET .../metadata-coverage,GET .../assets/without-metadata. -
pcli2 reportmanages report jobs - A new command group for the server-side reports (duplication, simplification, custom).report list [--type] [--status] [--limit](newest first; CSVID,NAME,TYPE,STATUS,PROGRESS,GROUPS,MIN_THRESHOLD,MAX_THRESHOLD,CREATED_AT,UPDATED_AT,CREATOR),report get --id,report download --id --format csv|xlsx [-o PATH](only a COMPLETED report; the file is streamed through a temporary file like an asset download; the default name is the report's name or id plus the extension),report diagnose --id(why a report failed, same shape and exit codes asasset diagnose),report delete --id(confirms unless--yes,--dry-run), andreport createfor a duplication report over--folder-pathfolders (subfolders included;--exclude-folder-path,--extension,--exclude-assemblies,--exclude-exact-duplicates,--include-home, thresholds default 80 to 100).--waitpolls until the report is COMPLETED, FAILED or CANCELLED (progress on stderr; a credential failure stops at once, any other polling error is retried up to three times in a row) and a report that ended FAILED or CANCELLED exits 69 with a pointer toreport diagnose.tenant failuresalready listed failed reports; their ids now have somewhere to go.
Changed
-
tenant metadata listJSON carries each field'sid- The registry listing always sent ids; the client now reads them, since rename and delete address a field by id. The CSV and tree output are unchanged. -
Dependencies are read by asset ID -
asset dependencies,folder dependenciesandasset dependency-diffnow useGET /tenants/{tenantId}/assets/{assetId}/dependencies-by-id, which looks the asset up by its stored path on the server, so the lookup keeps working after a folder is moved or renamed. The path-based/assets/{assetPath}/dependenciesendpoint the commands used is deprecated in Physna's specification. Output is unchanged in every format. The client now also reads each dependency'sstatus(matched,resolved,missing) and never asks the API about a missing dependency's children (it has no asset, so the only UUID to ask about was the nil one). -
--skip-existingasks the server instead of listing the folder -asset create-batch --skip-existingandfolder upload(which checks for existing names in both modes) now send the target paths toPOST /tenants/{tenantId}/assets/existing-paths, one request per 1000 files, instead of paging through the whole destination folder. Which files are skipped, theSkipping existing asset: ...lines, the counts and the "Asset already exists" error are unchanged. -
asset create --overridereplaces the file in place - When the asset exists and the new file has the same extension, the file is sent toPUT /tenants/{tenantId}/assets/{assetId}/file: the asset keeps its UUID, path and metadata and is re-indexed with the new content. Nothing is deleted, so a failed upload leaves the tenant as it was.--restore-metadatahas nothing to do in that case and says so. A file with a different extension still goes the old way (delete, then upload, with the conflict retry and the loss report).--override --dry-runnow says which of the two would happen and names the asset; without--overridethe dry-run line is unchanged. Uploads (asset create,asset create-batch,folder upload) go through the client's upload variant, which shares the token with the rest of the run; it makes no difference today because there is no separate upload timeout setting. -
asset gettakes several--uuidvalues - They are fetched with onePOST /tenants/{tenantId}/assets/batchrequest (up to 1000 per request) and printed as an asset list, in the same JSON and CSV shapes asasset list. Every id must exist: otherwise nothing is printed and the missing ids are named (exit 67). With one--uuidor--paththe output is unchanged. The client's batch method, which nothing used, now calls that endpoint instead of one request per asset.
Fixed
folder dependencieslists assemblies in a stable order - The JSON and tree output listed a folder's assemblies in a different order on every run (the folder listing is a map). They are now sorted by path, as the CSV rows already were.
Removed
- Four path-based dependency methods of the client library -
get_asset_dependencies_by_path,get_asset_dependencies_by_path_with_pagination,populate_asset_dependencies_recursive_by_pathand the unusedpopulate_asset_dependencies_recursive. Every command that used them holds the asset's UUID already and callsget_asset_dependencies_by_uuid.
2.1.0 - 2026-09-22
Added
asset diagnoseexplains why an asset failed to process (aliasesfailure,why) - Physna added on-demand failure diagnostics: the server searches its ingestion logs for the asset and answers with astatus(found,not-found,unavailable), akind(user, with a summary you can act on, orinternal, with a trace ID to quote to support), the summary, the trace ID and when it happened. The command takes--uuidor--path, prints JSON or CSV (ASSET_PATH,ASSET_STATE,STATUS,KIND,SUMMARY,TRACE_ID,OCCURRED_AT,ASSET_UUID), exits 0 forfoundandnot-found(with a stderr note saying whether the asset is simply not failed or the log entry has aged out), and exits 68 on a deployment without failure log search. Until now a failed asset was only visible as the wordfailedin aSTATEcolumn.tenant failureslists what failed lately - Assets, reports and part-finder reports in one listing, newest first, with--kindto narrow it (repeatable) and--limitto stop early. JSON output also carries the tenant-wide totals per kind; CSV isKIND,NAME,ID,FAILED_AT. TheIDof anassetrow is whatasset diagnose --uuidtakes.pcli2 doctorreports whether failure diagnostics are available - A newdiagnosticsline asks the deployment up front, so a customer-managed or enclave stack without log search is visible beforeasset diagnoseexits 68 there. It is a warning, never a failure.- Exit code 68 (service unavailable) is documented - It was defined but unused outside
doctor;asset diagnosenow uses it for a feature the deployment does not have.
Changed
asset similarityCSV carries every volumetric field - The API's volumetric block gained the mismatch-volume breakdown, the unmatched holes and the matched-hole distance in 2.0.2, but only the JSON output showed them. CSV now hasMISMATCH_VOLUME_TOTAL_MM3,SOURCE_MISS_MM3,TARGET_MISS_MM3,SOURCE_HOLE_MISS_MM3,TARGET_HOLE_MISS_MM3,MATCHED_HOLE_CENTER_DISTANCE_TOTAL_MM,SOURCE_HOLE_MISSESandTARGET_HOLE_MISSES(the last two are counts; the holes themselves are JSON-only) afterVOLUMETRIC_MATCH_PERCENTAGE. Every volumetric cell is empty, not0, when the tenant has no volumetric scoring or the API did not report that field. TheREFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUIDandCOMPARISON_URLcolumns moved right accordingly: read CSV columns by header name.- The spec review found no drift - The live OpenAPI specification is identical to the snapshot refreshed in 2.0.2, so no existing command changed. The three failure endpoints (
failure-diagnostics,failure-diagnostics/availability,failures) and their enumerations are now covered by the contract tests and the weekly drift check.
2.0.2 - 2026-09-21
Fixed
-
asset reprocessworks again - Physna removed the bulkPOST /tenants/{tenantId}/assets/reprocessendpoint the command used (spec 1.0.39, without a version bump). The command now calls the per-assetPOST /tenants/{tenantId}/assets/{assetId}/reprocess, which is the only reprocess endpoint left. Behaviour is unchanged: the asset is queued for indexing and the command prints nothing on success. -
The weekly spec-drift check reports the drift instead of crashing - Physna's CDN intermittently answers a bare HTTP client with an empty body, so the live-spec comparison panicked before it could compare anything (it had been failing that way since 14 September). The fetch now sends a browser user agent and retries an empty response up to five times.
-
cargo auditpasses again - rustls 0.23.43 carried RUSTSEC-2026-0285 (TLS 1.3 handshake messages accepted across encryption level boundaries). The lockfile pins 0.23.45. No other dependency moved.
Changed
- Volumetric match scores carry everything the API now returns -
asset similarityoutput includes the new optional volumetric fields when the tenant has volumetric scoring enabled:sourceHoleMisses,targetHoleMisses,matchedHoleCenterDistanceTotalMmandmismatchVolumeMm3. Existing fields and the CSV columns are unchanged. - The OpenAPI snapshot is refreshed to the current live specification, so the contract tests cover the current shapes. Besides the reprocess and volumetric changes above, the update touches only endpoints pcli2 does not call (reports, activity metrics, mold analysis, the viewer) and adds three new ones (
assets/existing-paths,assets/without-labels,labeling-coverage).
Removed
- Four unused client methods that called endpoints the API does not have -
update_folderandupdate_assetsentPUTrequests to paths that only acceptPATCH, andget_root_contents/list_folders_in_parentpassedcontentTypeandparentFolderIdto the folder listing, which ignores them. No command used any of them.
2.0.1 - 2026-09-06
Documentation
- The command reference and alias tables now cover every command - Every
pcli2 ...example in the README and the documentation site was checked against the binary's own help: all commands and flags exist. Twelve commands were missing from the README reference (asset similarity,config get path,config validate,user list,user get,cache clear,doctorand the environment commands), the alias tables lacked a dozen aliases, the feature lists still described resume as downloads-only and omitted the scripting flags and diagnostics, andpcli2 config get(a command group) was shown whereconfig get pathwas meant. No code changes.
2.0.0 - 2026-09-05
Removed
- The old spellings of the input and output flags -
--file(onasset createandconfig import),--files,--csv-file,--local-path,--fileonasset thumbnail, and the bare positional output path onasset downloadwere kept as hidden aliases by 1.27. They are gone. Each is still recognised so a script that uses one stops with exit 64 and a message naming the replacement (--input, or-o/--output), rather than clap's "unexpected argument". The README has the full mapping under "Upgrading to 2.0". This is the only change since 1.29.0, and the reason for the major version.
1.29.0 - 2026-09-05
Added
- Contract tests against Physna's OpenAPI specification - A snapshot of the spec now lives in
tests/fixtures/physna-openapi.json. For each of the 22 endpoints the client reads, a response body is generated from the spec's schema (once with only the required properties, once with all of them) and must deserialize into the model type the client uses, so a field Physna renames, drops or retypes fails in CI instead of as a deserialization error in a user's terminal. The asset states, metadata field types, dependency statuses and tenant roles the code hard-codes are compared with the spec's enumerations, the page sizes the client sends are checked against the spec's maximums, and every URL the client builds must exist. A weeklyspec-driftworkflow fetches the live spec and fails when any endpoint or schema the client depends on has changed, with the diff in the log and instructions for refreshing the snapshot.
Fixed
- Two things the contract tests found on their first run - A tenant without a display or short name (both optional in the spec) failed the whole tenant listing; both now default to empty. An asset listing without
pageData(optional in the spec, absent in cursor mode) was rejected; it now reads as a single page.
1.28.0 - 2026-09-05
Added
--safe-csv(global, orPCLI2_SAFE_CSV=1) - Guards every CSV cell this process writes against spreadsheet formula injection: a text cell starting with=,+,-,@, tab or carriage return is prefixed with a single quote, which Excel, LibreOffice and Google Sheets show as text. Numbers such as-5are left alone. Off by default because the quote is visible to other consumers of the file. Excel workbooks were already safe.
Fixed
PCLI2_NO_COLOR=0disabled colour in one place and enabled it in another - The terminal module treated any non-empty value as "disable" while clap parsed it as false. Both now follow one rule for pcli2 boolean variables: empty,0,false,noandoffmean off, anything else means on.NO_COLORkeeps the no-color.org rule (any non-empty value disables). The same rule is pinned onPCLI2_NO_INPUTandPCLI2_SAFE_CSV.--no-colorgiven as a value disabled colour - The terminal module scanned the raw command line, sotext-match --text --no-colorturned colour off. After parsing, the parsed flag is used; the raw scan only decides how clap colours its own help and error output before parsing.
1.27.0 - 2026-09-05
Changed
- One name per concept:
-i/--inputand-o/--output- Every command that reads a local file, directory or glob now takes--input:asset create(was--file),asset create-batch(was--files),asset metadata create-batch(was--csv-file),folder upload(was--local-path),config import(was--file). Every command that writes takes-o/--output:asset download(was a bare positional argument),asset thumbnail(was--file),folder downloadandfolder thumbnails(gained the-oshort form). The old spellings still work as hidden aliases, andasset downloadstill accepts the positional path, so no script breaks; only the help text and documentation changed. -qis now--quiet, and--forcehas no short form --fmeant--formaton about forty commands but--forceonfolder delete;-qwas--textontext-matchwhile--quiethad no short form.folder delete -fandtext-match -qno longer parse; use--forceand--text. These are the only two breaking changes in this release.- A flag that can change nothing now says so -
--prettywith CSV,--headerswith JSON or tree,--metadataonasset similarity, and format flags ontenant useused to be accepted in silence. They still are, but with a warning naming the flag and why it has no effect.
1.26.0 - 2026-09-05
Added
--error-format json(global, orPCLI2_ERROR_FORMAT=json) - Everything on stderr becomes one JSON object per line: errors with their hint and, for API errors, the HTTP status; warnings and log lines; the--statssummary. The final error object carries the process exit code and its class (usage,not_found,auth,api, ...), so a script reads one line instead of parsing prose. Usage errors clap reports before the command runs are JSON too.--no-input(global, orPCLI2_NO_INPUT=1) - Never prompt. A confirmation that would otherwise be asked fails with exit 64 and names--yes;tenant useandenv usewithout--namefail instead of opening a menu;auth loginfalls back to its missing-argument error. The same now happens without the flag whenever stdin is not a terminal.
Fixed
cache clearwithout a terminal exited 0 as "cancelled" - It read end-of-file as "no" and reported success to the calling script. It now refuses with exit 64 and asks for--yes.folder delete,asset deleteand the environment commands already refused; all five prompts now go through one function and give the same message.
1.25.0 - 2026-09-05
Added
--checkpoint FILEonfolder geometric-match,part-matchandvisual-match- Each asset's completed search is appended to FILE the moment it finishes, so an interrupted multi-hour run is no longer lost. Re-running the same command with the same file reuses the recorded results and searches only the remaining assets;stderrsays how many were reused. The file is fingerprinted with the search type, tenant, folders, threshold,--recursive,--exclusiveand--limit, and a file from a different run is refused instead of being mixed in. Only successful searches are recorded, so a run that stopped on expired credentials finishes afterpcli2 auth login. The file is deleted once the report has been written; it stays if the report fails, so a too-tall Excel workbook can be re-rendered as CSV without searching again.asset create-batch --skip-existing- Skips files whose name is already in the target folder, the same wayfolder upload --skip-existingdoes, so an interrupted batch upload can be re-run without creating duplicates.- Token renewal is now covered by tests against a mock API and auth server - A 401 renews once and the retry carries the new token; a burst of eight concurrent 401s costs one renewal; a client with credentials but no token authenticates before its first request; a rejected credential reports the auth server's reason and keeps the old token; and without credentials no renewal is attempted.
- Every formatter is checked for output shape - Each printable type is formatted in every output format it supports and checked for the properties scripts rely on: CSV parses with no ragged rows,
--headersadds exactly one line, nothing ends with a line break, compact JSON is one line, and an unsupported format is a clean error. This is what found the three fixes below.
Fixed
- Four tree outputs printed a trailing empty line -
tenant list,tenant metadata list,asset healthandasset dependency-diffin--format treeended with a line break thatprintln!doubled. - Four CSV outputs had no final line break at all -
auth token --format csv,asset metadata --format csv,asset visual-match --format csvandasset text-match --format csvwere printed withprint!after the 1.23.2 change made CSV text stop carrying its own line break, so the last line ran into the shell prompt andwc -lunder-counted by one. - An empty listing in CSV without headers printed one blank line - Every command now prints formatted output through one helper that prints nothing for an empty result, so
asset list --folder-path /Empty --format csv | wc -lis 0. - Text-match CSV rows had six fields under an eight-column header - The
TextMatchPairformatter wrote rows by hand that did not match its own header; the CSV writer rejected the combination outright. Rows now come from the same producer as the header. - The credentials file ignored
PCLI2_CONFIG_DIR- The documentation has said the variable holds bothconfig.ymland the credentials file; onlyconfig.ymlfollowed it, so a second profile shared the default profile's login. Both now live in the directory the variable names. Anyone who setPCLI2_CONFIG_DIRand logged in before this release will need to log in once more.
1.24.0 - 2026-09-04
Added
pcli2 doctor- One screen with everything support would otherwise ask for: which binary is running and whether others are on the PATH, whether the configuration loads, the active environment and its URLs, where credentials are stored (with the file's permissions), whether a usable token exists and when it expires, the active tenant, cache ages, whether the API and the auth server answer and how fast, and whether a newer release exists.--format jsonfor scripts. Exits 78 for a local problem, 68 when a server is unreachable, 0 otherwise.--statson every command prints one line on stderr at exit with the number of API requests, retries and token renewals and the elapsed time, so a run that hammers the server is visible to the person running it. The same line always goes to the debug log.
1.23.3 - 2026-09-04
Documentation
- Homebrew 6 requires a one-time
brew trust jchultarsky101/pcli2- Homebrew 6.0 refuses to load formulae from any tap that has not been trusted, sobrew installandbrew upgrade pcli2stop with "Refusing to load formula ... from untrusted tap" until the tap is trusted once per machine and user. The README and install guide now say so, including theHOMEBREW_NO_REQUIRE_TAP_TRUST=1escape hatch for CI. The installers, MSI andpcli2-updateare unaffected.
1.23.2 - 2026-09-04
Fixed
asset list --format csv(and asset, dependency and tenant-status CSV) no longer ends with an empty line - The 1.23.1 fix missed the formatters that name their buffer differently, which included the one every asset listing uses;asset list --folder-path X --format csv | wc -lstill over-counted by one. Every CSV and tree formatter now goes through the same trimming, and the two environment commands that printed without a final line break gained one. Checked at the byte level for thirty command and format combinations against a live tenant: each ends in exactly one line break and has no empty lines.
1.23.1 - 2026-09-04
Fixed
- CSV output no longer ends with an empty line - Every CSV-producing command (asset, folder, tenant, user, metadata, environment and configuration listings, match and dependency reports) terminated its output with two line breaks, so
asset list --format csv | wc -lreported one row more than there were assets and a spreadsheet opened the file with an empty last row. Verified across every listing command against a live tenant: line counts now equal row counts, and no command prints anything before or after its data.
1.23.0 - 2026-09-04
Changed
- Listings use the API's maximum page size - Folders, folder contents, assets, metadata fields, dependencies and users were fetched 200 at a time (searches 100) although the API accepts 1000 per page; a 10,000-folder tenant is now 10 requests instead of 50, and a folder of 20,000 assets 20 instead of 100. Search pages are 500.
--exclusiveis filtered by the server - Folder matches with--exclusivesent every search tenant-wide and discarded the out-of-scope rows client-side, which on a small folder in a large tenant meant downloading pages of results only to throw them away. The resolved folder UUIDs are now passed as the search'sfolderIdsfilter (which the API applies to the folders and their subfolders); the client-side check still decides the exact set, so output is unchanged.folder delete --forcehelp says what it does - The server deletes a folder recursively;--forceskips pcli2's own "not empty" refusal.
1.22.1 - 2026-09-04
Fixed
- A cycle in the server's folder data can no longer hang pcli2 - Every walk over the folder hierarchy (path building,
folder list --format tree, subtree filtering) now remembers where it has been, so a folder whose parent chain loops back on itself (or lists itself as its parent) ends the walk with a warning instead of looping forever or overflowing the stack. The "did you mean" suggestions build the path of every folder, so one bad record used to hang every not-found message.
1.22.0 - 2026-09-04
Fixed
- The new-version check no longer delays exit - It ran after the command finished and could hold the prompt for up to three seconds on a stale cache. It now starts before the command and is only reported at exit; a lookup still in flight is abandoned rather than waited for.
- Match percentages are formatted the same way in every CSV - Single-asset match CSV printed
100.0where the folder report and the--metadataCSV printed100. folder visual-matchsays when an asset hit--limit- The per-asset cap (default 100) truncated silently in folder mode; text match already warned.folder createprints the new folder's UUID - It printed nothing, so a script had to resolve the path it had just created.
Changed
- Root
--help(and the man page) list every environment variable pcli2 reads; the man page previously mentioned onlyPCLI2_NO_COLOR. - Folder match commands document their row order in
--help: pair order for CSV and JSON, match percentage for Excel. - Help text: "Folder UUID" instead of "Resource's folder UUID"; the
--outputhelp onfolder geometric-matchno longer contradicts itself.
1.21.0 - 2026-09-04
Fixed
-
The active tenant follows the environment - One tenant selection was shared by every environment, so
env use stagingleft production's tenant UUID active and every command failed with "Tenant not found" untiltenant usewas run again. Each environment now remembers its own tenant (older versions still read the top-level value). Folder and metadata caches are keyed by environment too, so a staging tenant cloned from production with the same UUID can no longer be served production's folder tree. -
Per-asset failure messages survive
--progress- During a folder match the reasons for individual failures, and the "stopping after repeated authentication failures" explanation, were written underneath the redrawing progress display and painted over (the same defect fixed for the scan spinner in 1.18.3). They are now printed with the display lifted. -
env reset,env removeand overwriting withenv addask first -env resetwiped every environment with no prompt;env addsilently replaced an existing one. All three honour the global--yes, and refuse rather than assume when no prompt can be shown. -
env addrejects a URL that is not one ---api-url 'not a url'was saved and surfaced later as an opaque request error. -
env remove --name nopesays the environment does not exist (exit 67) instead of "missing value for property". -
--format JSONworks - The value is matched case-insensitively, asPCLI2_FORMATalready was. -
asset list --folder-uuid- Every other folder command accepted a UUID; this one only took a path. -
user listshows itslsalias in help like every other list command. -
--verboseshows pcli2's own debug output without the HTTP stack's;RUST_LOGstill opens everything. -
Folder trees and lists sort case-insensitively ("alpha" before "Zeta").
-
Configuration and formatting errors show the cause as a sentence rather than a Rust debug dump.
-
asset deleteandfolder deletework again - The request-path rewrite in this release cycle sent the relative API path as the whole URL for DELETE; caught before release, with a regression test. -
asset metadata create-batchfetches the field registry once and lists each parent folder once - Both happened per row: a 5,000-row batch into a 10,000-asset folder was about a quarter of a million requests. A registry fetch that fails is now an error rather than "no fields exist", which used to turn every value into a new text field and report the API's rejection as a type conflict in the user's CSV. -
Cache files are written atomically and carry a schema version - Two pcli2 processes (a script under
xargs -P) could read a half-written cache and refetch the whole hierarchy; a cache written by another version is now discarded instead of decoded wrongly. A cache timestamp from the future no longer panics a debug build. -
Asset listing stops if the server echoes a stale page number - The page loop had no guard against being asked for the same page forever.
-
Listings that hit the safety page cap say so - The truncation of very large user and asset listings was logged at debug level only.
-
--files a,b,crejects a path that does not exist - It was dropped silently, so a typo uploaded one file fewer. Directories matched by a glob are skipped and counted instead of becoming per-file failures. -
asset metadata create --type numberno longer saturates large values -1e20was stored as 9223372036854775807.--type booleanwith a value that is not a boolean is sent as-is so the API rejects it, instead of silently writingfalse. -
asset metadata getprints{}(or CSV headers) for an asset without metadata - stdout used to be empty for a successful command, and JSON output was wrapped in an internal{"meta": ...}object. -
folder download --folder-uuidandfolder thumbnail --folder-uuidno longer write into a directory nameduntitled- The folder's name is used. -
folder uploadno longer copies every file through the temp directory - The copy used a non-unique name, so two uploads of files calledpart.stlfrom different directories could clobber each other mid-upload. -
asset create --overridetreats only "absent" as absent - A network or session failure while checking for the existing asset used to be read as "does not exist". -
A batch row whose folder does not exist is counted as missing, not as a permission problem.
-
A configured API URL with a trailing slash no longer produces
//tenantsURLs; user IDs are URL-encoded. -
tenant useinteractive selection no longer panics on a tenant name containing a colon. -
Excel report sorting parses each cell once instead of once per comparison (tens of millions of parses on a million-row report).
-
--tenantaccepts a tenant UUID, as its help text promised - Only the short name worked. A tenant missing from the cached list is also looked up once more from the API before it is reported as not found, so a tenant granted since the cache was written is usable withoutcache clear. -
PCLI2_FORMATis honoured byenv list,env getandconfig get---formathas a default value, so the branch that consulted the variable was unreachable. -
In-app advice no longer refers to a
contextcommand that does not exist - "Run 'pcli2 context set tenant'" is now "Run 'pcli2 tenant use'". -
Uploads go to the folder that was asked for - The upload endpoint places a file by the path string it is sent and creates any folder it does not know, and three callers sent it the wrong string:
folder upload --folder-uuidsent a placeholder/(every file landed at the tenant root),asset create --folder-uuidfell back to the bare folder name when the hierarchy fetch failed (a nested folderA/B/Cbecame a new top-levelC), and--folder-pathwas sent as typed, so/Home/Partscould create a literalHomefolder and/partsa second folder besideParts. The destination is now the folder's canonical path from the hierarchy, whichever way the folder was named. -
Uploading to the tenant root works -
asset create --folder-path /,asset create-batch --folder-path /andfolder upload --folder-path /failed with "Folder '/' not found" after fetching the whole hierarchy to suggest alternatives. The root has no UUID and needs none. -
Typed metadata compares equal to itself in match reports - A numeric or boolean field was rendered as text on the reference side and blanked on the candidate side, so the Excel diff painted every such field as "missing on one side" and CSV rows showed
42against an empty cell. Both sides now render values the same way (JSON text for non-strings, empty for null). -
Folder match JSON no longer invents reference asset fields -
referenceAssetreportedstate: "active"(not a Physna state),type: "asset",isAssembly: falseand empty timestamps regardless of the real asset. The real values are used. -
Single-asset text match CSV no longer doubles the asset URL - The stored URL was already an asset URL, and the CSV writer appended
/asset/<uuid>to it again. -
Excel reports stop at the worksheet hyperlink limit - Excel allows 65,530 hyperlinks per sheet; a report between that and the 1,048,574-row cap produced a workbook Excel "repairs" by stripping every link. Comparison URLs past the limit are written as plain text, with one warning.
-
Comma-separated values work where the help text promised them -
--name a,bonasset metadata deleteandasset metadata inference, and--folder-path a,bonfolder geometric-match,part-match,visual-matchandasset dependencies, were sent as one value containing a comma; a delete ofMaterial,Weightdeleted nothing and exited 0. -
Metadata batch CSV: the classic header is checked and short rows are reported - A file with columns in another order was applied positionally (paths and names swapped);
metadata get --format csvoutput (NAME,VALUE) was accepted and silently did nothing because every row was too short. The header must now readASSET_PATH,NAME,VALUE[,TYPE]; rows with fewer than three columns are counted and reported with line numbers; an empty NAME is an error. -
Downloaded names cannot escape the output directory - A folder or asset named
.., or a name containing a path separator, is refused instead of written outside the directory the user chose. -
One missing field no longer fails a whole page of assets -
type,createdAt,updatedAt,state,isAssemblyandmetadataare optional when deserializing, as are the page index fields. -
Ambiguous folder paths are reported - Two sibling folders that differ only by case (or not at all) both match a path; the first was used silently. A warning now names both UUIDs.
-
Batch commands exit non-zero when any item failed -
asset create-batchlogged failed files at debug level only and printed the successes with exit 0;asset metadata create-batch --continue-on-errorexited 0 with every row failed;folder upload,folder downloadandfolder thumbnailprinted "Operation completed successfully!" whatever had happened, and a missing thumbnail counted as a success. Every failure is now named on stderr and the command exits 69 (temporary failure) with a one-line count.--continue-on-errorstill decides whether the rest of the batch is attempted; it no longer decides whether the exit code tells the truth. -
folder downloadwithout--continue-on-errorstops at the first failure - It used to attempt every remaining asset anyway (each with its own 5-10 second retry sleep) and only then report an error; an expired session on file 1 of 5,000 cost 5,000 failing attempts. Remaining downloads are now cancelled and counted as "not attempted". -
Concurrent commands share one API client -
folder download,folder thumbnail,folder uploadandasset create-batchbuilt a fresh client inside every task: one credential-file read, one connection pool and one private token slot per asset, so a token expiring mid-run was renewed once per remaining asset (up to 22,000 auth-server calls in the largest known run) instead of once. Tasks now clone the caller's client, which shares the token, the renewal lock and the connection pool. -
folder uploadlists the destination folder once instead of once per file - Each task listed the entire folder (every page) to check whether its file already existed: 2,000 files into a folder of 10,000 assets was about 100,000 requests before the first upload. A failed listing was also treated as "does not exist", so--skip-existingcould re-upload on a transient error; it is now a hard error. -
folder downloadandfolder thumbnailno longer fetch every subfolder a second time - The subfolder listing already carries the name the walk needed; one request per subfolder is gone. -
Network and session failures while loading the folder hierarchy are no longer reported as "Folder not found" - The lookup swallowed them and every caller turned the empty answer into a path problem, sending users to check a path that was right. They now surface as what they are, and
--recursiveno longer suggestscache clearfor a failure that clearing the cache cannot fix. -
asset listandfolder listuse the folder cache - Both rebuilt the tenant's whole hierarchy from the API on every call (asset list --recursivetwice), andfolder list --reloadrefreshed nothing because the listing bypassed the cache. A path missing from the cached hierarchy triggers one refresh before it is reported absent, so a folder created since the cache was written is still found. -
Downloads are streamed to disk through a temporary file -
asset downloadandfolder downloadheld the whole file in memory (ten concurrent multi-gigabyte assemblies meant ten files in RAM), wrote directly to the final name so an interrupted transfer left a truncated file that looked complete, and accepted an empty body as success. The file is now streamed into<name>.partand renamed into place only when whole; an empty response is an error. The blind "sleep and retry any error, including 404" wrappers are gone: the client retries transient failures itself. -
Folder match runs count every failed task - A task that failed outside the search itself was dropped from the tally, so "Searched X of Y" and the 10% threshold used a smaller denominator. A run stopped by repeated authentication failures now always exits non-zero, even when the stop happened past the 90% mark.
-
Match runs read the configuration once - The UI base URL was loaded and parsed from disk for every match row: 1.29 million times on the largest known report.
-
"No assets to download" is a warning, not an error with exit 0 -
asset download-folderandfolder downloadprinted a red error and exited 0 for an empty folder. -
A server outage mid-run no longer produces a "complete" report with exit 0 - Every HTTP status other than 401/403/404 was wrapped in the same
Conflicterror the search endpoint uses for an asset that is not indexed, so a 500, 503 or 429 during a folder match was counted as "not searchable" - a property of the tenant, excluded from the failure threshold - and the run finished with a short report and a clean exit. Errors now carry their status: only a real 409 is "not searchable", and everything else counts as a failure that can fail the run. -
Transient failures are retried on every request, not only on DELETE - The API client built its requests on the raw HTTP client and skipped the retry helper entirely, so
PCLI2_MAX_RETRIES, the backoff, andRetry-Afterapplied to nothing the user cared about; one 503 in a 5,000-page match run aborted it. Every request now goes through one path with proactive token renewal, transient retry (connection errors, 408/429/502/503/504,Retry-Afterin seconds or HTTP-date form), and a single renew-and-retry on 401/403. Uploads re-open the file for each attempt; timed-out non-idempotent requests are still never resent. -
Exit codes follow the documented contract - Authentication failures exit 100, network failures 101, API errors 102, not-found 67, missing input files 66, an incomplete report 69, and usage errors from the argument parser 64 (previously 2). Every one of these used to exit 70 "internal software error" (or 0, see below), which made the
case $?examples in the README impossible to hit. -
Failures that exited 0 now exit non-zero -
auth getandauth expirationwith no token,env usewith no selection,env getwith no active or an unknown environment,tenant usewith no or an unknown tenant,config validatewhen validation fails, andconfig import, which was an unimplemented stub that reported success having done nothing and now says so. -
Error messages are no longer rewritten by substring - A folder named
401-serieswas reported as an authentication failure, an unknown environment name was replaced by "Resource not found", a file calledconnection-bracket.stlbecame a network error. Messages are now printed as the code produced them, with one hint chosen from what the error actually is (a login hint for authentication failures, a role hint for a 403 that survived token renewal, a connectivity hint for network errors). The OAuth error codes from the auth server keep their explanations, appended rather than substituted. -
Errors are printed once - Login and token failures were reported with remediation steps and then printed a second time on exit as a bare "Security error"; the incomplete-report error was printed twice with different counts.
-
A 404 no longer triggers a token renewal - Every not-found answer (a deleted asset, a wrong UUID) cost an auth-server call, a credential-file write and a retried request, and with a token-only login was then reported as an expired token. A 404 is now a not-found.
-
Automatic re-authentication failures say why - A rotated secret, a rate-limited auth endpoint and a DNS failure all printed the same "log in again"; the cause is now included.
-
Concurrent 401s collapse into one renewal - The check for "someone else already renewed" compared against the token current at the moment of the check rather than the token the failed request had used, so a task that read the shared slot after another task's renewal renewed again anyway.
-
Timeouts - A stalled connection used to wait out the full 30-minute request timeout even for a small JSON call, and the auth client had no timeout at all while holding the renewal lock, which hung every concurrent task with it. Connections now time out after 15 seconds and a read after 5 minutes of silence; the total timeout (
PCLI2_TIMEOUT, still 30 minutes by default) only bounds genuine long transfers. -
Every request identifies itself - The
User-Agentheader (nowPCLI2/<version>) was only sent on DELETE. -
Unsupported file types are no longer retried five times by
--override- The "Invalid path extension" upload rejection was classified as a conflict, which the override path treats as "the previous asset may still be deleting" and retries with backoff. It is now an invalid-parameter error, reported the same way whether or not the first attempt also hit an expired token. -
Thumbnail downloads on a Viewer account no longer make three auth-server calls per asset - The per-asset retry helper renewed the token up to three more times on any 403; the client's own renew-and-retry is enough.
Documentation
- The install guide had pointed at the wrong repository and listed a Rust toolchain as a prerequisite for the binary install; it now covers the shell and PowerShell installers, the Homebrew tap, the MSI,
pcli2-update, and says plainly that the crate is not on crates.io. The README no longer claims credentials are kept in the OS keychain: they live indev_credentials.jsonunder the configuration directory, owner-only on macOS and Linux.pcli2 config environment ...becamepcli2 env ...some releases ago and the README and quick start now say so;asset geometric-match-folderisfolder geometric-match; thecontextcommand istenant use/get/clear;--pathonasset listandfolder downloadis--folder-path; examples use/Home/..., the name Physna shows for the root, instead of/Root/.... Three environment variables (PCLI2_API_BASE_URL,PCLI2_UI_BASE_URL,PCLI2_AUTH_BASE_URL) that the code never read are gone from the docs, and every variable that is read is now listed in one table (README and Cross-Platform Configuration). The exit-code tables drop the code that is never emitted (68) and explain 64 for parser errors and 69 for partial batches. The documented multi-level inference propagation and theconfig importexample are removed with the features that did not exist.
Removed
- Dead dependencies -
bincode,exitcode,url,mime,tokio-utilandasync-recursion(recursion now usesBox::pin, stable since Rust 1.77);tempfilemoves to the test dependencies andtokio-testis dropped. Two integration test files that compiled to no tests (one was a single line of escaped text; the other asserted nothing) are removed and the test README describes what actually exists. The committed mdBook output underdocs/book/and the stale top-leveldocs/*.mdcopies are removed; the published site builds fromdocs/src/. The site no longer advertisescargo install pcli2.
Changed
-
CI runs
cargo auditand a minimum-supported-Rust check (1.88, set by transitive dependencies);rust-versionis declared inCargo.toml.Cargo.lockis no longer listed in.gitignore(it was tracked all along). -
asset metadata inference --recursive- The flag was accepted and never read; the documented multi-level propagation did not exist.
Changed
- Batch status lines go to stderr - The statistics reports of
folder upload,folder downloadandfolder thumbnail, and the per-file "Successfully uploaded" / "Skipping existing asset" lines, no longer share stdout with command output.