PCLI2

2.3.0 - 2026-09-23

v2.3.0 Sep 23 2026 at 05:06 UTC

Added

  • pcli2 api calls 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). -X sets the method, -F key=value and -f key=value build a JSON body, --input reads one from a file or standard input, and --paginate merges every page of a listing into one. Errors carry the server's message and the usual exit codes.
  • folder geometric-match --groups finds groups of duplicates - Assets connected by a chain of matches form a group; each row gets GROUP_ID and GROUP_SIZE as the last two columns (groupId/groupSize in 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 table and --columns - table prints aligned columns with a rule under the header, for every command that can print CSV. --columns path,uuid keeps 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_ENV choose the environment for one command - Without changing the saved default (pcli2 env use does that), so scripts can work against staging and production at the same time. An unknown name is refused before anything runs (exit 67).
  • PCLI2_TENANT sets --tenant for one command, and user list / user get accept --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 --quiet or --error-format json). --no-progress turns them off; --progress still forces them on.
  • Shorter aliases - gm, pm, vm and tm for the geometric, part, visual and text match commands; env ls and env rm. folder geometric-match --format xlsx is accepted as well as xls, and report list --type/--status accept any letter case.

Fixed

  • asset download no 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 the missing-dependencies state). The command assumed every assembly was a ZIP, so a raw file was saved as <name>.zip and then rejected with ZIP 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 -o path). 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.json was 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 as dev_credentials.json.unreadable-<time> with a warning instead of being overwritten. config.yml and the update-check cache are written the same atomic way.

  • pcli2 ... | head no 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-batch survives 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 login checks 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 upload onto an existing folder in that situation).

  • tenant list exits 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 / UNKNOWN instead of failing report list, tenant failures or asset dependencies with a JSON error. report create --wait keeps polling a status it does not know.

  • Names from the server are checked before they become local paths - asset download without -o, and folder download without -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 --recursive lists nested folders correctly - Below the top level it looked each subfolder up by a path missing its parents (B/C instead 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 / --recursive also includes the assets stored directly at the root, which it used to leave out.

  • folder download handles assemblies like asset 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 --resume never takes a half-extracted bundle for a finished one.

  • folder download names 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 in missing-dependencies are now downloaded. The others are counted in the summary as "Not downloaded" and listed with their state.

  • folder download and folder thumbnail accept 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 thumbnail also checks the folder name before using it as the output directory, and reports an empty folder as a warning rather than an error.

  • folder get and folder rename explain 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 counts also breaks ties between file types with the same count by name.

  • asset counts adds 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 as other in 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 OCCURRENCES column of asset dependencies and folder dependencies was 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 0 or 0.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_FORMAT works for every command - tenant list, tenant get, tenant state, tenant failures, tenant metadata list|assets|coverage|missing, asset metadata inference and folder part-match read --format themselves and never looked at the variable. They now honour it like the rest (an explicit --format still wins), and PCLI2_FORMAT=xls now works for folder geometric-match as --format xls does.

  • tenant use --name accepts a tenant UUID - As --tenant does. 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.toml and PTREE_* variables, so a user's settings could change what --format tree printed.

  • 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 list stopped at 5,000 users without saying so.

  • --limit no longer repeats or skips records - report list, tenant failures, tenant metadata assets and tenant metadata missing shrank the page size on the last request to fit --limit while the page number kept counting in the old size. --limit 1500 returned records 501-1000 twice and never 1001-1500.

  • folder upload and folder thumbnail stop cleanly - Without --continue-on-error they 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, as folder download does. folder upload refuses files that already exist (without --skip-existing) before uploading anything, naming all of them, instead of failing when their turn came. folder thumbnail writes each image whole or not at all.

  • asset metadata create-batch no 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-batch is 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 1 writes 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, no PCLI2_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 json gives JSON in the terminal too. The streaming folder match reports keep their formats. env list now 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-diff and asset resolve-dependency exit 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 thumbnail and the three folder match commands default to --concurrent 4 instead of 1 (the retry layer already backs off on rate limits). --concurrent 1 restores the old pace.
  • folder download and folder thumbnail start 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 audit warnings (unmaintained atty, ansi_term, yaml-rust, and the unsound lexical-core). inquire 0.9 and indicatif 0.18 remove two more unmaintained crates. The OS-keychain keyring crate is only built with the new os-keyring feature (--no-default-features --features os-keyring); the default build stores credentials in the file as before. Dependabot now proposes weekly updates against develop.
  • env add warns about plain http:// 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 caught pcli2 asset ls in the top-level help and several README asset list examples, which need --folder-path; the jq example now uses the real field file_size, the NuShell examples convert metadata values (which are strings in JSON) before comparing them, and the metadata "export, edit, reimport" workflow builds the ASSET_PATH,NAME,VALUE file create-batch actually reads.
  • Examples in --help for 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 login reads PCLI2_CLIENT_ID and PCLI2_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 through env:.
  • New pages: Credentials and Security (the credentials file is plain text; auth logout removes only the token), Proxies, Certificates and Timeouts, and Troubleshooting (by exit code). The quickstart selects a tenant right after logging in. metadata-inference.md now says what actually happens on a failure (the run stops at the first failed update). CONTRIBUTING.md replaces 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.md and HOMEBREW_TAP_SETUP.md (the Homebrew formula is published by the release workflow) and RELEASE_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_folder was never reachable from the CLI (folder download has its own implementation) and extracted archives into a predictable shared temporary directory.