PCLI2 Documentation
PCLI2 is the command-line client for the Physna public API: 3D geometry search, asset and folder management, metadata, and batch operations, with output that is built for scripts (JSON, CSV, Excel) as much as for people.
Chapters
Getting started
- Installation - Installers for every platform, updating, upgrading to 2.0, building from source
- Quick Start - Logging in, choosing a tenant, the everyday commands
Guides
- Geometric Matching - Finding similar assets, for one asset or a whole folder, and groups of duplicates
- Metadata Operations - Reading, writing and bulk-loading metadata
- Metadata Inference - Propagating metadata to geometrically similar assets
- Reports - Listing, downloading, explaining and starting the server-side reports
- Downloading and Uploading Folders - Bulk transfers, speed, resuming
- Scripting and Automation - Output formats, JSON errors, exit codes, prompts, retries, CI,
pcli2 api
Reference
- Command Reference - Every command and alias
- Configuration and Environment Variables - Environment variables and file locations
- Credentials and Security - Where the login is kept and what leaves your machine
- Proxies, Certificates and Timeouts - Corporate networks and firewalls
Help
- Troubleshooting - By exit code, and the common situations
Features
- Nested sub-commands with short aliases (
pcli2 asset ls,pcli2 folder rm) - Multiple environments (production, staging) and multiple tenants
- OAuth2 client-credentials login with automatic token renewal
- Asset upload, download, listing, deletion, reprocessing, thumbnails, and server-side failure diagnostics for assets that did not process
- Folder tree listing, creation, renaming, moving, bulk upload and download
- Geometric, part and visual matching, single-asset or folder-wide, with CSV and Excel reports
- Metadata fields: create, read, delete, bulk-load from CSV, infer from matches; rename and delete registered fields, see which assets use them and how many have none
- Reports: list, download (CSV/XLSX), explain a failed one, start a duplication report and wait for it
- Resumable runs: downloads skip files already on disk, uploads skip assets already in the folder, folder matches continue from a checkpoint file
- Retries with backoff for transient failures, and exit codes that say what went wrong
- Built for scripts:
--no-input,--error-format json,--safe-csv, andpcli2 doctorfor checking a setup
Start with the Installation Guide, then the Quick Start Guide.
Installation Guide
PCLI2 ships as pre-built binaries for macOS (Intel and Apple Silicon), Linux (x86_64 and aarch64) and Windows (x86_64). No Rust toolchain is needed unless you build from source.
Table of Contents
Installers
macOS and Linux: shell installer
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/jchultarsky101/pcli2/releases/latest/download/pcli2-installer.sh | sh
The script installs pcli2 and pcli2-update into ~/.cargo/bin (or the
directory it reports) and offers to add it to your PATH.
macOS and Linux: Homebrew
Homebrew 6 refuses formulae from taps it has not been told to trust, so the
first step is a one-time brew trust (per machine and user account):
brew trust jchultarsky101/pcli2
brew install jchultarsky101/pcli2/pcli2
Without it, brew install and every later brew upgrade pcli2 stop with
"Refusing to load formula jchultarsky101/pcli2/pcli2 from untrusted tap".
Homebrew 5 has no such check, but the first upgrade after moving to Homebrew 6
will. In CI, set HOMEBREW_NO_REQUIRE_TAP_TRUST=1 instead of trusting
interactively.
Windows: PowerShell installer
powershell -ExecutionPolicy Bypass -c "irm https://github.com/jchultarsky101/pcli2/releases/latest/download/pcli2-installer.ps1 | iex"
Windows: MSI
Download pcli2-x86_64-pc-windows-msvc.msi from the
latest release and run it.
Archives
Every release also carries plain archives (.tar.xz for macOS and Linux, .zip
for Windows) with the binary inside. Extract it and put it on your PATH.
Verifying the Installation
pcli2 --version
pcli2 --help
Shell completions and man pages are generated by the binary itself:
pcli2 completions zsh > ~/.zfunc/_pcli2 # or bash, fish, elvish, powershell
pcli2 man --output-dir ./man
Updating
| Installed with | Update with |
|---|---|
| Shell or PowerShell installer | pcli2-update |
| Homebrew | brew upgrade pcli2 (after the one-time brew trust jchultarsky101/pcli2 on Homebrew 6) |
| MSI | Download and run the newer MSI (the MSI does not ship the updater) |
PCLI2 prints a one-line hint on stderr when a newer release exists (at most once a
day, in terminal sessions only). Set PCLI2_NO_UPDATE_CHECK=1 to turn it off.
Upgrading to 2.0
Version 2.0 drops the old spellings of the input and output flags that 1.27 kept as hidden aliases. A script that still uses one stops with exit 64 and a message naming the replacement:
| Old | New |
|---|---|
asset create --file | asset create --input |
asset create-batch --files | asset create-batch --input |
asset metadata create-batch --csv-file | asset metadata create-batch --input |
folder upload --local-path | folder upload --input |
config import --file | config import --input |
asset thumbnail --file | asset thumbnail --output |
asset download <path> (positional) | asset download --output <path> |
Nothing else changed between 1.29 and 2.0.
Building from Source
Requires a Rust toolchain (1.88 or newer) and, on Linux, pkg-config,
libssl-dev and cmake.
git clone https://github.com/jchultarsky101/pcli2.git
cd pcli2
cargo build --release
# The executable is target/release/pcli2
PCLI2 is not published on crates.io, so cargo install pcli2 does not work.
Troubleshooting
- Command not found: the install directory is not on your
PATH; the installer prints the directory it used. - An old version keeps running:
which -a pcli2(orwhere pcli2on Windows) lists every copy on thePATH; remove the stale one. - Build failures from source: update Rust with
rustup update stable.
If you are stuck, open an issue at GitHub Issues.
Quick Start Guide
This guide will help you get started with PCLI2 quickly by walking through common tasks.
Install PCLI2 first: see Installation.
Table of Contents
- Authentication
- Choosing a Tenant
- Basic Navigation
- Working with Assets
- Geometric Matching
- Metadata Operations
- Configuration
- Multi-Environment Configuration
- Next Steps
- Getting Help
Authentication
Before using most PCLI2 commands, you need to authenticate with your Physna tenant. First, you'll need to obtain your API credentials.
Getting API Credentials
There are two methods to obtain your API credentials:
Method 1: Using the Physna Web Interface (Recommended)
This is the newer, more user-friendly approach available to administrators:
- Log in to your Physna instance
- (Optional) Select a tenant from the tenant selector
- Click on Settings (the gear icon in the top-right corner)
- Navigate to the Users tab
- Create a new service account
- Record the Client ID and Client Secret for use with PCLI2
Method 2: Using the API Documentation Page (Legacy)
This is the original approach using the API documentation interface:
- Navigate to the Physna OpenAPI Documentation page
- Log in with your Physna credentials
- Locate and execute the
POST /users/me/service-accountsendpoint - Record the Client ID and Client Secret from the response
Logging In
Once you have your credentials, you can authenticate with PCLI2:
# Login interactively (prompts for the client ID and secret, with
# masked input so the secret never lands in your shell history)
pcli2 auth login
# Login without a prompt (scripts, CI): credentials from the environment
PCLI2_CLIENT_ID=... PCLI2_CLIENT_SECRET=... pcli2 auth login
# Verify authentication
pcli2 auth get
Choosing a Tenant
Most commands act on the active tenant. Pick it once; --tenant overrides it for
a single command.
# List the tenants your credentials can reach
pcli2 tenant list
# Make one active, by short name or by UUID
pcli2 tenant use --name demo
pcli2 tenant use --name 123e4567-e89b-12d3-a456-426614174000
# Show the active tenant
pcli2 tenant get
# Clear it
pcli2 tenant clear
Basic Navigation
Learn to navigate your Physna tenant using PCLI2:
# List available tenants
pcli2 tenant list
# List folders in the root directory (shows only direct children, not entire subtree)
pcli2 folder list
# List folders in tree format to see the complete hierarchy
pcli2 folder list --format tree
# List assets in a specific folder
pcli2 asset list --folder-path /Home/MyFolder/
Working with Assets
Asset management is a core function of PCLI2. These commands allow you to upload, retrieve, organize, and maintain your 3D models and other assets in Physna.
Uploading Assets
The asset create command uploads individual files to your Physna tenant, placing them in the specified folder path. This is useful for adding single assets to your collection:
# Upload a single asset
pcli2 asset create --input path/to/my/model.stl --folder-path /Home/MyFolder/
# Replace an existing asset's file in place (same UUID, path and metadata; re-indexed)
pcli2 asset create --input path/to/my/model.stl --folder-path /Home/MyFolder/ --override
# A file with a different extension is deleted and uploaded again instead;
# --restore-metadata re-applies the old asset's metadata in that case
pcli2 asset create --input path/to/my/model.step --folder-path /Home/MyFolder/ --override --restore-metadata
For bulk operations, asset create-batch allows you to upload multiple files at once using glob patterns:
# Upload multiple assets
pcli2 asset create-batch --input "models/*.stl" --folder-path /Home/BatchUpload/
Viewing and Managing Assets
Use these commands to inspect and manage your assets:
# View asset details
pcli2 asset get --path /Home/MyFolder/model.stl
# Delete an asset
pcli2 asset delete --path /Home/MyFolder/model.stl
# Move an asset to another folder (it keeps its UUID and metadata)
pcli2 asset move --path /Home/MyFolder/model.stl --folder-path /Home/Archive
# See what failed to process lately, then ask the server why
pcli2 tenant failures --kind asset --format csv --headers
pcli2 asset diagnose --path /Home/MyFolder/model.stl
Geometric Matching
Geometric matching is a powerful feature that allows you to find assets with similar 3D geometry in your Physna tenant. This is particularly useful for identifying duplicate parts, finding design variations, or discovering similar components across different projects.
# Find matches for a single asset
pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 85.0
# Find matches for all assets in a folder (parallel processing)
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --threshold 90.0 --format csv --progress
The threshold parameter controls the similarity requirement, where higher values (closer to 100) require closer matches. The progress flag provides visual feedback during long-running operations.
Metadata Operations
Metadata is essential for organizing and searching your assets effectively. PCLI2 supports comprehensive metadata operations including creating, retrieving, updating, and deleting asset metadata. Metadata helps you categorize, filter, and find assets based on custom properties like material, supplier, weight, or any other characteristic relevant to your workflow.
Creating and Updating Metadata
The metadata create command adds or updates a single metadata field on an asset. This is useful for setting specific properties on individual assets:
# Add or update a single metadata field on an asset
pcli2 asset metadata create --path "/Home/Folder/Model.stl" --name "Material" --value "Steel" --type "text"
# A number field (run once per field)
pcli2 asset metadata create --path "/Home/Folder/Model.stl" --name "Weight" --value "15.5" --type "number"
Retrieving Metadata
Use the metadata get command to view all metadata associated with an asset:
# Get all metadata for an asset
pcli2 asset metadata get --path "/Home/Folder/Model.stl"
Deleting Metadata
The metadata delete command removes specific metadata fields from an asset without affecting other metadata on the same asset:
# Delete specific metadata fields from an asset
pcli2 asset metadata delete --path "/Home/Folder/Model.stl" --name "Material" --name "Weight"
# Delete metadata fields using comma-separated list
pcli2 asset metadata delete --path "/Home/Folder/Model.stl" --name "Material,Weight,Description"
Metadata Inference
Metadata inference automatically applies metadata from a reference asset to geometrically similar assets. This feature helps you efficiently propagate metadata across similar assets, reducing manual work and ensuring consistency in your asset database:
# Apply specific metadata fields from a reference asset to similar assets
pcli2 asset metadata inference --path /Home/Folder/ReferenceModel.stl --name "Material,Cost" --threshold 85.0
# Several fields, repeating --name, with a looser threshold
pcli2 asset metadata inference --path /Home/Folder/ReferenceModel.stl --name "Material" --name "Finish" --name "Supplier" --threshold 80.0
The metadata operations help you efficiently manage your asset metadata, whether you need to add, update, retrieve, or delete specific metadata fields, or propagate metadata across geometrically similar assets.
Configuration
Manage your PCLI2 configuration:
# Where the configuration file is
pcli2 config get path
# Export configuration for backup
pcli2 config export --output my-config.yaml
Multi-Environment Configuration
PCLI2 supports multiple environment configurations, allowing you to easily switch between different Physna instances (e.g., development, staging, production):
# Add a new environment configuration
pcli2 env add --name "development" \
--api-url "https://dev-api.physna.com/v3" \
--ui-url "https://dev.physna.com" \
--auth-url "https://dev-auth.physna.com/oauth2/token"
# Add a production environment
pcli2 env add --name "production" \
--api-url "https://app-api.physna.com/v3" \
--ui-url "https://app.physna.com" \
--auth-url "https://physna-app.auth.us-east-2.amazoncognito.com/oauth2/token"
# List all environments
pcli2 env list
# Switch to an environment (with interactive selection)
pcli2 env use
# Or switch to an environment by name
pcli2 env use --name development
# Get details of the active environment
pcli2 env get
# Get details of a specific environment
pcli2 env get --name production
# Reset all environment configurations
pcli2 env reset
Each environment can have its own:
- API base URL (for API calls)
- UI base URL (for comparison viewer links)
- Authentication URL (for OAuth2 token requests)
Next Steps
- Geometric Matching for folder-wide match reports
- Metadata Operations for bulk metadata loading from CSV
- Scripting and Automation for exit codes, JSON output and CI use
- Cross-Platform Configuration for environment variables
Getting Help
For help with any command, use the built-in help system:
# Install man pages for offline reference (man pcli2, man pcli2-asset-create, ...)
mkdir -p ~/.local/share/man/man1 && pcli2 man --output-dir ~/.local/share/man/man1
# General help
pcli2 --help
# Help for a specific command group
pcli2 asset --help
# Help for a specific command
pcli2 asset create --help
You can also use the -h or --help flag with any command to get detailed usage information.
Geometric Matching
PCLI2 provides powerful geometric matching capabilities to find similar assets in your Physna tenant. This feature leverages advanced algorithms to identify assets with similar geometries, regardless of their orientation, scale, or position.
Table of Contents
- Overview
- Single Asset Matching
- Folder-Based Matching
- Direct Asset Similarity (Match Scores)
- Threshold Settings
- Performance Options
- Error Handling
- Best Practices
- Advanced Usage
- Troubleshooting
Overview
Geometric matching helps you:
- Find duplicate or near-duplicate assets
- Identify variations of the same part
- Locate similar components across different projects
- Reduce storage costs by identifying redundant assets
- Improve design workflows by finding existing similar parts
Related Features
Geometric matching serves as the foundation for other powerful capabilities:
- Metadata Inference: Automatically propagate metadata from reference assets to geometrically similar assets using
pcli2 asset metadata inference - Metadata Management: Create, update, retrieve, and delete metadata for assets using commands like
pcli2 asset metadata create,pcli2 asset metadata get, andpcli2 asset metadata delete - Part Family Management: Organize and categorize groups of similar components
- Design Optimization: Identify opportunities for part consolidation and standardization
Single Asset Matching
Find geometrically similar assets for a specific reference asset.
Basic Usage
# Find matches for a specific asset
pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 80.0
# Using asset UUID instead of path
pcli2 asset geometric-match --uuid 123e4567-e89b-12d3-a456-426614174000 --threshold 85.0
# Find matches with CSV output and headers
pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 80.0 --format csv --headers
# Find matches with CSV output, headers, and metadata
pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 80.0 --format csv --headers --metadata
Output Formats
JSON Format (Default)
[
{
"referenceAssetName": "ReferenceModel.stl",
"candidateAssetName": "SimilarModel.stl",
"matchPercentage": 95.75,
"referenceAssetPath": "/Home/Folder/ReferenceModel.stl",
"candidateAssetPath": "/Home/DifferentFolder/SimilarModel.stl",
"referenceAssetUuid": "123e4567-e89b-12d3-a456-426614174000",
"candidateAssetUuid": "987fc321-fedc-ba98-7654-43210fedcba9"
}
]
CSV Format
REFERENCE_ASSET_NAME,CANDIDATE_ASSET_NAME,MATCH_PERCENTAGE,REFERENCE_ASSET_PATH,CANDIDATE_ASSET_PATH,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL
ReferenceModel.stl,SimilarModel.stl,95.75,/Home/Folder/ReferenceModel.stl,/Home/DifferentFolder/SimilarModel.stl,123e4567-e89b-12d3-a456-426614174000,987fc321-fedc-ba98-7654-43210fedcba9,https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=68555ebf-f09c-4861-96b1-692d2ec10de7&tenant2Id=68555ebf-f09c-4861-96b1-692d2ec10de7&searchType=geometric&matchPercentage=95.75
CSV Format with Metadata
When using the --metadata flag, the output includes metadata fields from both the reference and candidate assets. This produces CSV output with additional metadata columns prefixed with REF_ for reference asset metadata and CAN_ for candidate asset metadata. The output also includes a COMPARISON_URL column that provides a link to view the comparison in the Physna UI:
REFERENCE_ASSET_PATH,CANDIDATE_ASSET_PATH,MATCH_PERCENTAGE,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL,REF_MATERIAL,CAN_MATERIAL,REF_COLOR,CAN_COLOR
/Home/Folder/ReferenceModel.stl,/Home/DifferentFolder/SimilarModel.stl,95.75,123e4567-e89b-12d3-a456-426614174000,987fc321-fedc-ba98-7654-43210fedcba9,https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=68555ebf-f09c-4861-96b1-692d2ec10de7&tenant2Id=68555ebf-f09c-4861-96b1-692d2ec10de7&searchType=geometric&matchPercentage=95.75,Steel,Aluminum,Red,Blue
All metadata fields from all matched assets are included as columns, with empty values for assets that don't have a particular metadata field.
Complete Examples
Here are complete examples showing the command with and without the --metadata flag:
Without metadata:
pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 80.0 --format csv --headers
Output:
REFERENCE_ASSET_PATH,CANDIDATE_ASSET_PATH,MATCH_PERCENTAGE,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL
/Home/Folder/ReferenceModel.stl,/Home/DifferentFolder/SimilarModel.stl,95.75,123e4567-e89b-12d3-a456-426614174000,987fc321-fedc-ba98-7654-43210fedcba9,https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=68555ebf-f09c-4861-96b1-692d2ec10de7&tenant2Id=68555ebf-f09c-4861-96b1-692d2ec10de7&searchType=geometric&matchPercentage=95.75
With metadata:
pcli2 asset geometric-match --path /Home/Folder/ReferenceModel.stl --threshold 80.0 --format csv --headers --metadata
Output:
REFERENCE_ASSET_PATH,CANDIDATE_ASSET_PATH,MATCH_PERCENTAGE,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL,REF_MATERIAL,CAN_MATERIAL,REF_COLOR,CAN_COLOR
/Home/Folder/ReferenceModel.stl,/Home/DifferentFolder/SimilarModel.stl,95.75,123e4567-e89b-12d3-a456-426614174000,987fc321-fedc-ba98-7654-43210fedcba9,https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=68555ebf-f09c-4861-96b1-692d2ec10de7&tenant2Id=68555ebf-f09c-4861-96b1-692d2ec10de7&searchType=geometric&matchPercentage=95.75,Steel,Aluminum,Red,Blue
Threshold Settings
The threshold parameter controls the minimum similarity percentage required for a match:
- 0.0 - Return all possible matches (may include unrelated assets)
- 50.0 - Very loose matching (many potential matches)
- 80.0 - Default setting (good balance of accuracy and recall)
- 90.0 - Strict matching (high confidence matches)
- 95.0+ - Very strict matching (near duplicates only)
Folder-Based Matching
Find geometrically similar assets for all assets in a specified folder. This command processes assets in parallel for improved performance.
Basic Usage
# Find matches for all assets in a folder
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --threshold 85.0
Including Subfolders
By default only the assets sitting directly in the named folder are matched. A folder that holds nothing but subfolders therefore produces no report:
# /Creo Files contains 8 subfolders and no assets of its own
pcli2 folder geometric-match --folder-path "/Creo Files" --threshold 85.0
# ❌ Error: No assets found directly in the specified folder(s)
# 1. The folder(s) contain 8 subfolder(s) - pass --recursive to include the assets in them
Pass --recursive (-R) to walk the whole subtree:
# Matches every asset under /Creo Files, including all of its subfolders
pcli2 folder geometric-match --folder-path "/Creo Files" --threshold 85.0 --recursive
--recursivecan widen the scope dramatically — a folder with one asset of its own may have thousands underneath it, and each one costs a search. Raise--concurrent(up to 10) to speed it up, or name a deeper folder to narrow the scope.
The same flag is available on folder part-match and folder visual-match.
Comparison Viewer URL
Both geometric-match and folder geometric-match commands include a comparison URL in their output that allows you to view the geometric match in the Physna UI. The URL is available in both JSON and CSV formats:
- JSON: The field is named
comparisonUrl - CSV: The column is named
COMPARISON_URL
The URL follows this format:
https://app.physna.com/tenants/{tenant_short_name}/compare?asset1Id={reference_asset_uuid}&asset2Id={candidate_asset_uuid}&tenant1Id={tenant_uuid}&tenant2Id={tenant_uuid}&searchType=geometric&matchPercentage={match_percentage}
Excel (XLSX) Output
In addition to json and csv, the folder match command supports --format xls,
which writes a color-highlighted Excel workbook designed for a human reader.
It contains exactly the same columns, in the same order, as the CSV output
(always including the REF_/CAN_ metadata pairs), rendered with visual aids
that make a large report easy to scan:
- Frozen headers and identity columns — the two header rows and the leading reference path, candidate path, and match-percentage columns stay in view while you scroll a wide, tall report.
- Grouped metadata pairs — each
REF_<field>/CAN_<field>pair is boxed and labeled once with the field name (e.g.MATERIALover aREFand aCANsub-column), so the reference/candidate pairs stand out among the plain columns. - Metadata diff highlighting — for every pair, both cells are shaded: 🟩 green when the two values match, 🟥 red when they differ, and 🟨 amber when a value is present on only one side.
- Match-score heat map — the
MATCH_PERCENTAGEcolumn is shaded on a gradient (cool at 0%, through yellow at 50%, to red-hot at 100%) and the rows are sorted by match percentage, highest first. - Clickable comparison links —
COMPARISON_URLis the last column (its long value is rarely read, so the metadata columns come before it), written as a hyperlink you can click to open the side-by-side comparison in a browser. - A Summary sheet after the matches records how the report was made (tenant,
folders, threshold,
--exclusive, the time and the pcli2 version) and what it found: the number of pairs, how many assets they involve, how many groups of matching assets there are (see below), and how the match percentages are distributed (100%, 99 to 100%, 95 to 99%, 90 to 95%, under 90%).
Because Excel is a binary format, xls writes to a file rather than standard
output. Use --output (or -o) to choose the path; if omitted, the workbook is
written to match_report.xlsx in the current directory. The extension is always
normalized to .xlsx (the modern Office Open XML format); if it had to be
changed, a warning is printed to stderr. On success the command follows the
UNIX convention of printing nothing to stdout.
# Write a highlighted Excel report for a folder
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --threshold 80.0 --format xls --output report.xlsx
# Multiple folders, default output filename (match_report.xlsx)
pcli2 folder geometric-match --folder-path /Home/FolderA/ --folder-path /Home/FolderB/ --format xls
The
xlsformat always includes metadata (the metadata diff is its whole point), so the--metadataflag is implied and does not need to be passed.
Groups of Duplicates
A report lists pairs: ten copies of one part in a folder make forty-five rows.
--groups also says which assets belong together. Two assets are in the same
group when a chain of matches connects them (A matches B and B matches C: A, B
and C are one group), and every row gets the group's number and size as two extra
last columns, GROUP_ID and GROUP_SIZE (groupId and groupSize in JSON).
Groups are numbered in the order the rows list them, so the same data always
numbers them the same way. Without --groups the report is unchanged.
# Duplicate groups as CSV: sort by GROUP_ID to review one part at a time
pcli2 folder geometric-match --folder-path /Home/Parts/ --threshold 99 --groups --format csv --headers > duplicates.csv
Performance Options
Concurrency Control
Control how many simultaneous operations are performed (range: 1-10, default: 1):
# Use 8 concurrent operations (default is 4, maximum is 10)
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --concurrent 8
# Use the default (4 concurrent operations)
pcli2 folder geometric-match --folder-path /Home/SearchFolder/
# Invalid values are refused before anything runs (exit 64)
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --concurrent 15 # error: concurrency must be between 1 and 10, got 15
Progress Tracking
Display progress information during long-running operations:
# Show progress information
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --progress
# Combine with concurrency to show multiple progress bars (one per concurrent operation)
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --concurrent 8 --progress
When using both --concurrent and --progress flags together, the command will display:
- An overall progress bar showing the total completion percentage
- Individual progress bars for each concurrent operation showing which assets are being processed
- Status messages indicating the current stage of each operation (starting search, processing matches, completion)
With --recursive, --progress also covers the folder scan that happens before
any matching starts. A deep tree costs one API call per folder, so this phase can
run for a while on its own:
⠹ Scanning /Creo Files: 46/312 folders, 1174 assets found
followed by a summary once the scan completes:
Scanned 1 folder path(s), found 3182 asset(s) to match
All of this goes to stderr, so piping stdout to a file or another command is
unaffected. Without --progress the scan is silent.
Performance Options
Concurrency and Progress Combined
For optimal performance monitoring, combine both options:
# Use 10 concurrent operations with detailed progress tracking
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --concurrent 10 --progress
# Combine with other options
pcli2 folder geometric-match --folder-path /Home/SearchFolder/ --threshold 85.0 --concurrent 8 --progress
Resuming an Interrupted Run
A match over a large tenant can run for hours, and until the report is written
nothing has been saved. --checkpoint FILE changes that: every asset's result
is appended to FILE the moment its search finishes, and re-running the same
command with the same file reuses what was recorded and searches only the
assets that are left.
# First attempt - interrupted after two hours
pcli2 folder geometric-match --folder-path "/Creo Files" --recursive \
--threshold 85 --concurrent 8 --progress \
--checkpoint creo-match.jsonl --format csv --headers > creo-matches.csv
# Same command again: picks up where it stopped
pcli2 folder geometric-match --folder-path "/Creo Files" --recursive \
--threshold 85 --concurrent 8 --progress \
--checkpoint creo-match.jsonl --format csv --headers > creo-matches.csv
On the second run stderr reports what was reused:
Resuming from checkpoint 'creo-match.jsonl': 2,431 of 3,182 asset(s) already searched
Points worth knowing:
- The file is tied to the exact run: search type, tenant, folder paths,
--threshold,--recursive,--exclusiveand (for visual search)--limit. A file written by a different combination is refused with a message naming the run it belongs to; delete it or pick another path. - Only successful searches are recorded. An asset whose search failed is
searched again on the next run, which is also how a run that stopped on
authentication failures is completed after
pcli2 auth login. - The file is deleted once the report has been written successfully. It stays if the report fails - for example an Excel workbook too tall for a worksheet - so the same searches are not repeated after fixing the output options.
- The output format is not part of the fingerprint: an interrupted CSV run can be finished as JSON or Excel.
- Assets added to the folder between runs are searched; assets removed are dropped from the report.
part-match and visual-match take the same option.
Handling Large Folders
For folders with many assets, consider these strategies:
- Use a checkpoint:
--checkpoint FILEmakes an interruption cost minutes instead of hours - Adjust threshold: Higher thresholds reduce processing time
- Increase concurrency: Use more concurrent operations (but watch resource usage)
- Process in batches: Break large folders into smaller subfolders
Direct Asset Similarity (Match Scores)
While geometric-match searches your tenant for assets similar to a single
reference, asset similarity compares two specific assets and returns the
pairwise match scores between them. Use it when you already know both assets you
want to compare.
Each asset can be identified by either its UUID or its path — PCLI2 resolves paths to UUIDs automatically:
- Reference (source) asset:
--reference-uuidor--reference-path - Candidate (target) asset:
--candidate-uuidor--candidate-path
Both assets must be 3D models in a finished state, and they must be different assets (comparing an asset with itself is rejected by the API).
Basic Usage
# Compare two assets by path
pcli2 asset similarity \
--reference-path /Home/Folder/block1.stl \
--candidate-path /Home/Folder/block2.stl
# Mix identifiers: reference by UUID, candidate by path
pcli2 asset similarity \
--reference-uuid 123e4567-e89b-12d3-a456-426614174000 \
--candidate-path /Home/Folder/block2.stl
# CSV output with headers
pcli2 asset similarity \
--reference-path /Home/Folder/block1.stl \
--candidate-path /Home/Folder/block2.stl \
--format csv --headers
The command is also available under the alias
pcli2 asset match-scores.
Output Formats
JSON Format (Default)
{
"referenceAssetPath": "/Home/Folder/block1.stl",
"referenceAssetUuid": "123e4567-e89b-12d3-a456-426614174000",
"candidateAssetPath": "/Home/Folder/block2.stl",
"candidateAssetUuid": "987fc321-fedc-ba98-7654-43210fedcba9",
"geometric": {
"matchPercentage": 90.21,
"forwardMatchPercentage": 86.58,
"reverseMatchPercentage": 86.58
},
"volumetric": {
"matchPercentage": 74.2,
"sourceHoleMisses": [
{"centerMm": {"x": 12.5, "y": 0.0, "z": 4.0}, "axis": {"x": 0.0, "y": 0.0, "z": 1.0}, "radiusMm": 2.5}
],
"targetHoleMisses": [],
"matchedHoleCenterDistanceTotalMm": 0.75,
"mismatchVolumeMm3": {
"sourceMissMm3": 10.5,
"targetMissMm3": 20.25,
"sourceHoleMissMm3": 1.5,
"targetHoleMissMm3": 0.0,
"totalMm3": 32.25
}
},
"comparisonUrl": "https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=tenant-uuid&tenant2Id=tenant-uuid&searchType=geometric&matchPercentage=90.21"
}
The geometric scores describe how similar the two models are:
- matchPercentage: Overall geometric similarity (100% = geometrically identical)
- forwardMatchPercentage: How much of the reference asset's geometry exists in the candidate
- reverseMatchPercentage: How much of the candidate asset's geometry exists in the reference
The volumetric object is included only when volumetric scoring is enabled
for your tenant; otherwise it is omitted entirely. Contact Physna sales to
enable it. Volumetric scores are cross-format and tessellation invariant, and
carry everything the API reports:
- matchPercentage: How much of the reference asset's volume is contained in the candidate
- mismatchVolumeMm3: The volume the two do not share, in cubic millimetres, split
into
sourceMissMm3/targetMissMm3(solid volume with no counterpart on the other side),sourceHoleMissMm3/targetHoleMissMm3(the same for holes) andtotalMm3 - sourceHoleMisses / targetHoleMisses: The holes found on one side with no
counterpart on the other, each with its aligned centre (
centerMm), unit axis andradiusMm - matchedHoleCenterDistanceTotalMm: The summed centre-to-centre distance of the holes that did match
Only matchPercentage is guaranteed inside volumetric; the API omits the other
fields when it has nothing to report, and so does the JSON output.
CSV Format
REFERENCE_ASSET_PATH,CANDIDATE_ASSET_PATH,MATCH_PERCENTAGE,FORWARD_MATCH_PERCENTAGE,REVERSE_MATCH_PERCENTAGE,VOLUMETRIC_MATCH_PERCENTAGE,MISMATCH_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_MISSES,TARGET_HOLE_MISSES,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL
/Home/Folder/block1.stl,/Home/Folder/block2.stl,90.21,86.58,86.58,74.2,32.25,10.5,20.25,1.5,0,0.75,1,0,123e4567-e89b-12d3-a456-426614174000,987fc321-fedc-ba98-7654-43210fedcba9,https://app.physna.com/tenants/demo-1/compare?asset1Id=123e4567-e89b-12d3-a456-426614174000&asset2Id=987fc321-fedc-ba98-7654-43210fedcba9&tenant1Id=tenant-uuid&tenant2Id=tenant-uuid&searchType=geometric&matchPercentage=90.21
The nine volumetric columns (VOLUMETRIC_MATCH_PERCENTAGE through
TARGET_HOLE_MISSES) are empty unless volumetric scoring is enabled for your
tenant, and any single one is empty when the API did not report that field. An
empty cell means "not reported", not zero. SOURCE_HOLE_MISSES and
TARGET_HOLE_MISSES are counts of unmatched holes; the holes themselves (centre,
axis, radius) are only in the JSON output. Read CSV columns by header name: the
volumetric columns were added in 2.1.0, which moved the UUID and URL columns to
the right.
Error Handling
Common Errors
HTTP 409 Conflict
A 409 from the search endpoint means the asset cannot be searched in its current state: it is still indexing, has no 3D data, or failed to index. This is a property of the tenant, not of the run, so the asset is counted as "not searchable" in the summary and the run continues; it is not retried. Transient failures (connection errors, 408/429/502/503/504) are retried with backoff, and a 401/403 triggers one token renewal and retry. A run that loses more than 10% of its searches to operational failures, or that is stopped by repeated authentication failures, exits 69 rather than producing a report that looks complete.
Permission Denied
When you don't have permission to perform geometric search:
ERROR: Error: Access forbidden. You don't have permission to perform geometric search on this asset.
Check your tenant permissions and API credentials.
Asset Not Found
When the specified asset or folder cannot be found:
ERROR: The asset with ID 'XXX' cannot be found in tenant 'YYY'
Verify the asset path or UUID is correct.
Best Practices
Optimizing Performance
- Use appropriate thresholds: Start with 80-85% and adjust based on results
- Limit search scope: Use specific folders rather than searching entire tenants
- Monitor resource usage: Adjust concurrency based on your system capabilities
- Use progress tracking: Monitor long-running operations
Interpreting Results
- High match percentages (>95%): Likely duplicates or very similar assets
- Medium match percentages (80-95%): Similar geometry with variations
- Low match percentages (<80%): May be false positives or loosely related
Automation Tips
- Schedule regular deduplication: Run geometric matching periodically to identify duplicates
- Integrate with CI/CD: Use geometric matching in automated workflows
- Export results: Use CSV format for easy analysis in spreadsheets
Advanced Usage
Scripting Examples
Bash Script for Regular Deduplication
#!/bin/bash
# deduplicate.sh
FOLDERS=("/Home/ProjectA/" "/Home/ProjectB/" "/Home/Archive/")
THRESHOLD=95.0
CONCURRENT=8 # Number of concurrent operations
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
for folder in "${FOLDERS[@]}"; do
echo "Processing folder: $folder"
pcli2 folder geometric-match \
--folder-path "$folder" \
--threshold $THRESHOLD \
--concurrent $CONCURRENT \
--format csv \
--progress \
> "duplicates_${folder//\//_}_$TIMESTAMP.csv"
done
echo "Deduplication complete. Results saved to CSV files."
PowerShell Script for Windows
# deduplicate.ps1
$Folders = @("/Home/ProjectA/", "/Home/ProjectB/", "/Home/Archive/")
$Threshold = 95.0
$Concurrent = 8 # Number of concurrent operations
$Timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
foreach ($folder in $Folders) {
Write-Host "Processing folder: $folder"
pcli2 folder geometric-match `
--folder-path $folder `
--threshold $Threshold `
--concurrent $Concurrent `
--format csv `
--progress `
> "duplicates_$($folder.Replace('/', '_'))_$Timestamp.csv"
}
Write-Host "Deduplication complete. Results saved to CSV files."
Troubleshooting
Performance Issues
If matching operations are taking too long:
- Reduce concurrency: Lower the
--concurrentvalue - Increase threshold: Use higher threshold values to reduce matches
- Check network: Ensure good connectivity to the Physna API
- Monitor server status: Check if the Physna service is experiencing issues
Incomplete Results
If you're not seeing expected matches:
- Lower threshold: Try lower threshold values
- Check asset types: Ensure assets are compatible geometric file types
- Verify permissions: Confirm you have access to all assets in the search scope
- Contact support: If issues persist, reach out to Physna support
Related Commands
asset geometric-match- Find matches for a single assetfolder geometric-match- Find matches for all assets in a folderasset similarity- Get pairwise match scores between two specific assets (alias:asset match-scores)asset list- List assets in a folderasset get- Get detailed asset information
Use pcli2 asset geometric-match --help, pcli2 folder geometric-match --help, and pcli2 asset similarity --help for detailed command information.
Catalog Search
A catalog is a Physna tenant that other tenants may search into, such as a
supplier catalog. pcli2 catalog takes an asset from one of your own tenants
and finds matching parts in a catalog: "does a supplier already sell this
part?"
Catalog search is enabled by Physna per customer. If it has not been enabled
for you, pcli2 catalog list prints nothing and warns, and the match commands
exit 68.
Table of Contents
Which Catalogs You Can Search
pcli2 catalog list
pcli2 catalog list --format csv --headers
NAME,DESCRIPTION,ID,ROLE
catalog,Supplier Catalog,a0d94427-d7eb-4b28-b624-49c68ce83686,search
The list is read from the server on every run, so a catalog Physna has just enabled shows up without clearing any cache.
Matching an Asset
The asset is named the usual way, by --path or --uuid, in the active tenant
or the one given with --tenant. --in names the catalog; with only one
catalog it can be left out. PCLI2_CATALOG sets it for every command, and is
checked the same way.
# Visually similar catalog parts, the top 20
pcli2 catalog visual-match --path /Home/Parts/bracket.stl --limit 20
# Geometric matches of 90% or better, as CSV
pcli2 catalog geometric-match --path /Home/Parts/bracket.stl --threshold 90 --format csv --headers
# Part search in a named catalog
pcli2 catalog part-match --uuid <ASSET_UUID> --in catalog
| Command | Alias | --threshold means |
|---|---|---|
catalog geometric-match | gm | minimum similarity, 0-100 (default 80) |
catalog part-match | pm | minimum similarity, 0-100 (default 80) |
catalog visual-match | vm | size tolerance, 0-100; 0 turns size filtering off |
Every command returns at most --limit matches (default 100) and warns when
there were more.
Metadata search and the combined search are not offered: Physna refuses the first for a catalog, and the second currently fails on the server.
Output
The CSV has the same columns as the corresponding asset command, with a
CATALOG column after the candidate's path:
REFERENCE_ASSET_PATH,CATALOG,CANDIDATE_ASSET_PATH,MATCH_PERCENTAGE,REFERENCE_ASSET_UUID,CANDIDATE_ASSET_UUID,COMPARISON_URL
part-match has FORWARD_MATCH_PERCENTAGE,REVERSE_MATCH_PERCENTAGE in place
of MATCH_PERCENTAGE; visual-match has no score column. The comparison link
opens both assets side by side in the web application.
JSON output is one object: searchType, referenceAsset, catalog and
matches.
What Is Never Searched
--in accepts only the catalogs catalog list shows. If your account can see
several tenants (production and staging, or more than one company), naming any
of them that is not a catalog is refused before anything is searched, so one
tenant's search is never answered with another tenant's data. As a further
guard, a match the server returns from outside the chosen catalog is dropped,
with a warning.
The asset must be in one of your own tenants; an asset of the catalog itself cannot be searched from.
Exit Codes
| Code | When |
|---|---|
| 0 | The search ran (with or without matches) |
| 64 | --in is not one of your catalogs, or you have several and named none |
| 68 | Catalog search is not enabled for your account |
| 102 | The API refused a request, for example an asset UUID that does not exist (as with asset visual-match) |
Metadata Operations
PCLI2 provides comprehensive metadata operations for managing asset metadata including creating, retrieving, updating, and deleting asset metadata.
Overview
Metadata is essential for organizing and searching your assets effectively. PCLI2 supports comprehensive metadata operations to help you manage your asset metadata efficiently.
Metadata Operations
PCLI2 provides several commands for working with asset metadata:
1. Create/Update Individual Asset Metadata
Add or update a single metadata field on an asset:
# Add or update a single metadata field on an asset
pcli2 asset metadata create --path "/Home/Folder/Model.stl" --name "Material" --value "Steel" --type "text"
# Add or update a single metadata field on an asset by UUID
pcli2 asset metadata create --uuid "123e4567-e89b-12d3-a456-426614174000" --name "Weight" --value "15.5" --type "number"
2. Retrieve Asset Metadata
Get all metadata for an asset:
# Get all metadata for an asset in JSON format (default)
pcli2 asset metadata get --path "/Home/Folder/Model.stl"
# Get all metadata for an asset in CSV format (suitable for batch operations)
pcli2 asset metadata get --uuid "123e4567-e89b-12d3-a456-426614174000" --format csv
3. Delete Asset Metadata
Delete specific metadata fields from an asset:
# Delete specific metadata fields from an asset
pcli2 asset metadata delete --path "/Home/Folder/Model.stl" --name "Material" --name "Weight"
# Delete metadata fields using comma-separated list
pcli2 asset metadata delete --uuid "123e4567-e89b-12d3-a456-426614174000" --name "Material,Weight,Description"
4. Create/Update Metadata for Multiple Assets
Create or update metadata for multiple assets from a CSV file:
# Create or update metadata for multiple assets from a CSV file
pcli2 asset metadata create-batch --input "metadata.csv"
CSV Formats for Batch Metadata Operations
The create-batch command accepts two CSV layouts. The layout is detected automatically from the header row: if any column name starts with metadata:, the file is treated as the UI (horizontal) format; otherwise it is treated as the classic (vertical) format. You can also force a layout explicitly with --csv-format classic or --csv-format ui (the default is --csv-format auto).
In both layouts, empty values are skipped by default: the existing metadata field on the asset, if any, is left untouched, so a sparse file can be used to incrementally add or update fields. Pass --delete-if-empty to instead delete a metadata field from the asset when the file contains an empty value for it — useful when replacing an asset's metadata wholesale.
Classic (Vertical) Format
The classic CSV format used by asset metadata get --format csv and asset metadata create-batch --input is designed for seamless round-trip operations:
ASSET_PATH,NAME,VALUE,TYPE
/Home/Folder/Model1.stl,Material,Steel,text
/Home/Folder/Model1.stl,Weight,15.5,number
/Home/Folder/Model2.ipt,Inventory Qty,42,number
/Home/Folder/Model2.ipt,Supplier Link,https://example.com/,url
/Home/Folder/Model2.ipt,Exportable,true,boolean
The CSV format specifications:
- Header Row: Must contain
ASSET_PATH,NAME,VALUEin that order, optionally followed byTYPE - ASSET_PATH: Path to the asset in Physna (e.g.,
/Home/Folder/Model.stl). A leading/Home— the name Physna shows for the root folder — is treated as the root, so/Home/NX/part.prt,/NX/part.prt, andNX/part.prtall refer to the same asset - NAME: Name of the metadata field to set
- VALUE: Value to assign to the metadata field. Values are automatically coerced to the field's type (see Metadata Field Types). An empty value is skipped by default, or deletes the field from the asset when
--delete-if-emptyis passed - TYPE (optional): One of
text(default),number,boolean, orurl. This only governs the type used when registering a new field; for a field that already exists in Physna, the existing registered type is authoritative and theTYPEcolumn is ignored. The column is optional per row — some rows may include it and others may omit it - File Encoding: Must be UTF-8 encoded
- Quoting: Values containing commas, quotes, or newlines must be enclosed in double quotes
- Escaping: Double quotes within values must be escaped by doubling them (e.g.,
"15.5"" diameter") - Empty Rows: Will be ignored during processing
- Multiple Fields: If an asset has multiple metadata fields to update, include multiple rows with the same ASSET_PATH but different NAME and VALUE combinations
Example Command:
# Create/update metadata for multiple assets from a CSV file
pcli2 asset metadata create-batch --input "metadata.csv"
Deleting metadata fields via CSV:
Pass --delete-if-empty and leave the VALUE column empty to remove a metadata field from an asset:
ASSET_PATH,NAME,VALUE
/Home/Folder/Model1.stl,ObsoleteField,
/Home/Folder/Model1.stl,Material,Steel
pcli2 asset metadata create-batch --input "metadata.csv" --delete-if-empty
In the example above, ObsoleteField is deleted and Material is set to Steel in a single pass. Without --delete-if-empty, the ObsoleteField row would be skipped with a warning and only Material would be updated.
Note: The create-batch command groups all rows by asset path, then issues deletes (empty values, when --delete-if-empty is passed) followed by updates (non-empty values) per asset in one batch. Multiple rows with the same ASSET_PATH are combined into a single API interaction.
UI (Horizontal) Format
The Physna web UI's bulk metadata upload uses a horizontal layout with one row per asset and one column per metadata field. create-batch accepts these files directly:
"path","id","metadata:Material","metadata:Color","metadata:Weight"
"/domain/assets/part1.sldprt","123e4567-e89b-12d3-a456-426614174000","Steel","Blue","2.5kg"
"/domain/assets/part2.step","","Aluminum","Red","1.2kg"
"/domain/assets/assembly.sldasm","","Mixed","",""
The UI format specifications:
- path: Full path to the asset in Physna
- id: Optional asset UUID. When present and non-empty, it takes precedence over the path and is used directly, without path resolution. An invalid UUID is an error (there is no fallback to the path, since that could silently target a different asset)
- metadata:<field name>: One column per metadata field. The
metadata:prefix is stripped to obtain the field name - Empty metadata cells: Skipped by default — the existing field value on the asset, if any, is left untouched. With
--delete-if-empty, an empty cell deletes the field from the asset instead - Other columns: Any column that is not
path,id, ormetadata:*is ignored, with a warning listing the ignored columns - Row identification: Each row must provide a UUID or a path; a row with neither is an error
The whole file is parsed and validated before any API call is made, so a malformed file (e.g. an invalid UUID) fails fast with a line-numbered error instead of half-applying.
# Auto-detected from the header row
pcli2 asset metadata create-batch --input "ui-export.csv"
# Or forced explicitly
pcli2 asset metadata create-batch --input "ui-export.csv" --csv-format ui
Listing a Tenant's Registered Metadata Fields
Metadata fields are registered per tenant, each with a name and a type. Use
tenant metadata list to see every field currently registered in the active
tenant:
# JSON (default)
pcli2 tenant metadata list
# CSV, ready to turn into a create-batch file
pcli2 tenant metadata list --format csv --headers
The CSV output uses the same column headers as the classic create-batch
input (ASSET_PATH,NAME,VALUE,TYPE), with NAME and TYPE filled from the
registry and ASSET_PATH and VALUE left blank:
ASSET_PATH,NAME,VALUE,TYPE
,Description,,text
,Exportable,,boolean
,Inventory Qty,,number
,Supplier Link,,url
,Unit Price ($),,number
This makes it easy to build a batch-upload template: save the listing, then for
each asset fill in ASSET_PATH and VALUE (replicating the field rows per
asset). Because values are coerced to each field's registered type, you do not
need to touch the TYPE column for fields that already exist.
# Save the field list as a starting template
pcli2 tenant metadata list --format csv --headers > fields.csv
Managing the Registry
The same command group renames and deletes fields, and reports how they are used. Fields are addressed by their exact registered name; an unknown name lists the registered ones.
# Rename a field; the values already on assets are kept
pcli2 tenant metadata rename --name "Unit Price ($)" --new-name "Unit Price (USD)"
# Delete a field nobody uses any more (asks for confirmation; --yes skips it)
pcli2 tenant metadata delete --name "Old Field"
# A field that assets still use is refused unless --force, which also removes
# its value from every asset that had one
pcli2 tenant metadata delete --name "Old Field" --force --yes
# See what would happen first
pcli2 tenant metadata delete --name "Old Field" --force --dry-run
# Which assets have a value for a field (same columns as `asset list`)
pcli2 tenant metadata assets --name "Supplier Link" --format csv --headers
# How much of the tenant is covered by metadata at all
pcli2 tenant metadata coverage --format csv --headers
# The assets with no metadata at all, oldest first, narrowed by folder and type
pcli2 tenant metadata missing --folder-path /Home/Parts --extension stl --limit 50 --format csv --headers
coverage prints the counts and the percentage:
COVERED_ASSETS,TOTAL_ASSETS,COVERAGE_PERCENT
16143,23580,68.5
Demo assets uploaded by Physna are excluded from both coverage and missing.
Advanced Metadata Workflow: Export, Modify, Reimport
One of the most powerful features of PCLI2 is the ability to export metadata, modify it externally, and reimport it:
-
Export Metadata in the
ASSET_PATH,NAME,VALUElayout thatcreate-batchreads.asset metadata getshows one asset's fields asNAME,VALUE(no path, so it cannot be imported back); for a folder, build the file from the JSON listing withjq:pcli2 asset list --folder-path "/Home/Folder/" --metadata --format json \ | jq -r '["ASSET_PATH","NAME","VALUE"], (.[] | .path as $p | (.metadata // {}) | to_entries[] | [$p, .key, .value]) | @csv' \ > folder_metadata.csv -
Modify Metadata Externally:
- Open the CSV file in a spreadsheet application (Excel, Google Sheets, etc.)
- Make the desired changes to metadata values
- To delete a field, clear its VALUE cell (leave it blank) and reimport with
--delete-if-empty - Save the file in CSV format
-
Reimport Modified Metadata:
# Update assets with modified metadata (blank values are skipped) pcli2 asset metadata create-batch --input "modified_metadata.csv" # Or replace metadata wholesale: blank values delete the field from the asset pcli2 asset metadata create-batch --input "modified_metadata.csv" --delete-if-empty
This workflow enables powerful bulk metadata operations while maintaining the flexibility to use familiar spreadsheet tools for data manipulation.
Metadata Field Types
PCLI2 supports four metadata field types:
-
Text (default): String values
pcli2 asset metadata create --path "/Home/Model.stl" --name "Description" --value "Sample part description" --type "text" -
Number: Numeric values
pcli2 asset metadata create --path "/Home/Model.stl" --name "Weight" --value "15.5" --type "number" -
Boolean: True/False values
pcli2 asset metadata create --path "/Home/Model.stl" --name "Approved" --value "true" --type "boolean" -
URL: Link values (stored as a string)
pcli2 asset metadata create --path "/Home/Model.stl" --name "Supplier Link" --value "https://example.com/" --type "url"
Automatic type coercion
Every metadata field in a tenant is registered with a type, and the Physna API
rejects a value whose JSON type does not match. Because a CSV cell is just text,
PCLI2 coerces each value to the field's registered type before sending it —
so create-batch works against typed fields without you having to declare
anything:
- A
numberfield receives18(a JSON number) rather than the string"18";84.50is sent as84.5 - A
booleanfield acceptstrue/false,1/0,yes/no,on/off(case-insensitive) textandurlfields store the value as a string
If a value cannot be represented as the field's type — for example the text
N/A for a number field — that row is a type conflict and is reported as
an error (see create-batch Error Behavior).
The registered type always wins. The
--typeflag (singlecreate) and theTYPEcolumn (batch) only decide the type used when a field is registered for the first time; they cannot change the type of an existing field. To change a field's type, delete and recreate it.
Best Practices
- Use Descriptive Names: Choose clear, consistent names for metadata fields across your organization
- Validate Data Types: Ensure values match the expected data type for each field
- Batch Operations: Use CSV batch operations for large-scale metadata updates
- Backup Before Bulk Operations: Export metadata before performing bulk deletions
- Test First: Use small test sets before applying operations to large asset collections
- Use Proper Authentication: Ensure your credentials have appropriate permissions for metadata operations
Error Handling
Metadata operations provide detailed error messages, retry transient network failures internally, and validate input formats before processing.
create-batch Error Behavior
By default, asset metadata create-batch stops on the first error and prints a summary of how many assets were processed successfully. This makes failures visible instead of letting a batch silently complete with partial results.
Specifically:
- CSV parsing errors: always terminate immediately — the input file is expected to be well-formed
- Unresolvable asset paths (asset not found): by default, terminates the batch. Pass
--continue-on-errorto skip the failing asset and continue with the remaining rows - Metadata update/delete failures, including type conflicts (a value that cannot be represented as the field's registered type): by default, terminate the batch. Pass
--continue-on-errorto skip the offending asset and continue with the remaining rows - Authentication failures: always terminate with a remediation message directing the user to re-authenticate, regardless of
--continue-on-error
With --continue-on-error, skipped assets are reported with a concise warning as they are encountered, and the final summary reports how many assets succeeded and how many failed.
Example — skip both unresolvable paths and conflicting values:
pcli2 asset metadata create-batch --input "metadata.csv" --continue-on-error
On completion (or termination), a summary is printed to stderr showing the number of successful and failed assets.
Speed and Order
Every row's asset is looked up before anything is written (UUIDs a thousand per
request), new fields are registered once, and then the rows are written four at
a time. --concurrent N changes that (1 to 10); --concurrent 1 writes strictly
in file order. A row whose asset cannot be found stops the batch before the first
write (or is skipped with --continue-on-error).
Progress
# A progress bar during long batch operations
pcli2 asset metadata create-batch --input "metadata.csv" --progress
Integration with Other Commands
Metadata operations work seamlessly with other PCLI2 commands:
# Export results for auditing
pcli2 asset metadata get --path "/Home/Parts/Model.stl" --format csv > metadata_export.csv
Limitations
- API Rate Limits: Extensive operations may be rate-limited by the Physna API
- Processing Time: Large batch operations can take considerable time
- Metadata Types: Supports text, number, boolean, and url metadata fields
- Asset Access: Can only process assets accessible to your authenticated user
- Field Names: Metadata field names must be unique per asset and follow Physna naming conventions
Always test operations on a small scale before running them on large datasets.
Metadata Inference
The metadata inference feature allows you to automatically apply metadata from a reference asset to geometrically similar assets, significantly reducing manual metadata entry work.
Overview
Metadata inference works by:
- Taking a reference asset and specified metadata fields
- Finding geometrically similar assets using the Physna geometric search
- Applying the reference metadata to matching assets
This is particularly useful for applying common metadata like materials, categories, suppliers, or costs to families of similar parts.
Basic Usage
Apply metadata from a reference asset to similar assets:
pcli2 asset metadata inference --path /Home/Parts/Bolt-M8x20.stl --name "Material" --threshold 90.0
This command will:
- Find the asset at
/Home/Parts/Bolt-M8x20.stl - Extract the "Material" metadata field value
- Find all assets with 90% or higher geometric similarity
- Apply the same "Material" value to all matching assets
Specifying Multiple Metadata Fields
You can apply multiple metadata fields in a single operation:
# Using comma-separated values
pcli2 asset metadata inference --path /Home/Parts/BaseModel.stl --name "Material,Cost,Supplier" --threshold 85.0
# Using multiple --name flags
pcli2 asset metadata inference --path /Home/Parts/BaseModel.stl --name "Material" --name "Cost" --name "Supplier" --threshold 85.0
Threshold Values
The threshold parameter controls the similarity requirement for matching assets:
- Range: 0.00 to 100.00
- Higher values: More stringent matching (fewer but more similar matches)
- Lower values: More permissive matching (more but less similar matches)
- Recommended starting point: 80.00-85.00 for most use cases
# Very strict matching (high similarity required)
pcli2 asset metadata inference --path /Home/Parts/Reference.stl --name "CriticalField" --threshold 95.0
# Liberal matching (find more potential matches)
pcli2 asset metadata inference --path /Home/Parts/Reference.stl --name "GeneralField" --threshold 75.0
Practical Examples
Applying Standard Materials
# Apply standard material to a family of similar bolts
pcli2 asset metadata inference --path /Home/StandardParts/Bolt-M8x20.stl --name "Material" --threshold 92.0
Categorizing Product Lines
# Assign category and supplier information to a product family
pcli2 asset metadata inference --path /Home/ProductLine/MainAssembly.stl --name "Category,Supplier,Division" --threshold 85.0
Cost Propagation
# Apply estimated costs to similar components
pcli2 asset metadata inference --path /Home/Components/ReferenceBracket.stl --name "EstimatedCost,Currency" --threshold 88.0
Best Practices
1. Start with Conservative Thresholds
Begin with higher threshold values (85-90%) to ensure high-quality matches, then adjust based on results:
pcli2 asset metadata inference --path /Home/Parts/Reference.stl --name "Material" --threshold 90.0
2. Test with Non-Critical Metadata
Start by applying metadata to non-critical fields to understand the matching behavior:
pcli2 asset metadata inference --path /Home/Test/Reference.stl --name "TestTag" --threshold 85.0
3. Combine with Geometric Matching
Use geometric matching first to preview results, then apply metadata inference:
# Preview matches
pcli2 asset geometric-match --path /Home/Parts/Reference.stl --threshold 85.0 --format csv
# Apply metadata if preview looks good
pcli2 asset metadata inference --path /Home/Parts/Reference.stl --name "Material" --threshold 85.0
Error Handling
The command checks before it changes anything, then stops at the first failure:
- The reference asset has none of the named fields: the command stops before searching, with exit 64, and names the fields it looked for.
- The reference asset does not exist: exit 67.
- A metadata update fails (a permission problem, a type conflict with an existing field): the command stops there. Assets updated before the failure keep their new values; the error says which asset failed.
- Network hiccups are retried by the client before they count as a failure, as for every command.
Because a run can stop partway, preview the matches first (see above) and run it again after fixing the cause: assets that already carry the values are simply written again.
Integration with Other Commands
# Keep a record of what was changed
pcli2 asset metadata inference --path /Home/Parts/Reference.stl --name "Category" --threshold 85.0 \
--format csv --headers > metadata_propagation_log.csv
Limitations
- API Rate Limits: Large operations may be rate-limited by the Physna API
- Processing Time: Large operations can take considerable time
- Metadata Types: Supports text, number, boolean and url metadata fields
- Asset Access: Can only process assets accessible to your authenticated user
Always test operations on a small scale before running them on large datasets.
Reports
Physna builds reports on the server: duplication reports (groups of similar
assets), simplification reports and custom reports. They are jobs that run for
a while and then hold data you can download. pcli2 report lists, inspects,
downloads, explains and deletes them, and starts duplication reports.
Table of Contents
- Listing Reports
- One Report
- Downloading the Data
- Why a Report Failed
- Deleting a Report
- Creating a Duplication Report
- Exit Codes
Listing Reports
# Every report, newest first
pcli2 report list
# Only finished duplication reports, as CSV
pcli2 report list --type DUPLICATION --status COMPLETED --format csv --headers
# The five most recent
pcli2 report list --limit 5
ID,NAME,TYPE,STATUS,PROGRESS,GROUPS,MIN_THRESHOLD,MAX_THRESHOLD,CREATED_AT,UPDATED_AT,CREATOR
f046e5b8-c08b-4bbb-b685-c6fd85e4d1b1,Custom 9/21/2026,CUSTOM,COMPLETED,100,1,80,100,2026-09-21T18:33:10.382Z,2026-09-21T18:33:11.254Z,someone@physna.com
98e51614-3e5b-4eee-957b-fa19699535ce,Custom 9/21/2026,CUSTOM,FAILED,20,0,80,100,2026-09-21T18:13:25.987Z,2026-09-22T14:16:24.033Z,someone@physna.com
--type takes DUPLICATION, SIMPLIFICATION or CUSTOM; --status takes
PENDING, RUNNING, COMPLETED, FAILED or CANCELLED. The JSON output is
an array of the full report records, including the folders, extensions and
thresholds the report was created with.
One Report
pcli2 report get --id f046e5b8-c08b-4bbb-b685-c6fd85e4d1b1 --format json --pretty
Downloading the Data
Only a COMPLETED report has data. The file is streamed through a temporary
.part file and renamed into place once it has arrived whole, like an asset
download, so an interrupted transfer never leaves a truncated file.
# CSV under the report's name (here: "Custom 9_21_2026.csv")
pcli2 report download --id f046e5b8-c08b-4bbb-b685-c6fd85e4d1b1 --format csv
# Excel workbook, to a path of your choice
pcli2 report download --id f046e5b8-c08b-4bbb-b685-c6fd85e4d1b1 --format xlsx -o dupes.xlsx
A report that is still PENDING or RUNNING is refused with exit 69 (try
again later); one that FAILED or was CANCELLED is refused with exit 64.
Why a Report Failed
tenant failures lists failed reports beside failed assets. report diagnose
asks the server why, from its job logs, exactly like asset diagnose does for
an asset:
pcli2 report diagnose --id 98e51614-3e5b-4eee-957b-fa19699535ce
{
"reportId": "98e51614-3e5b-4eee-957b-fa19699535ce",
"reportName": "Custom 9/21/2026",
"reportStatus": "FAILED",
"status": "found",
"kind": "internal",
"summary": "Processing failed inside Physna.",
"traceId": "d55c845b-80f1-44fb-95df-256aebf7bf3c",
"occurredAt": "2026-09-21T18:13:26.000Z"
}
status: not-found (exit 0) means the report did not fail, or the log entry
has aged out; a note on stderr says which. On a deployment without failure log
search the command exits 68.
Deleting a Report
pcli2 report delete --id 98e51614-3e5b-4eee-957b-fa19699535ce --dry-run
pcli2 report delete --id 98e51614-3e5b-4eee-957b-fa19699535ce --yes
Without --yes the command asks for confirmation (and refuses with exit 64
under --no-input).
Creating a Duplication Report
A duplication report groups assets that match each other between two similarity thresholds (80% to 100% by default). It searches the folders you name, subfolders included.
# Start it and print the record (status PENDING)
pcli2 report create --name "Brackets" --folder-path /Home/Parts/Brackets --extension stl
# Start it, follow it to the end, then download the data
pcli2 report create --name "Brackets" --folder-path /Home/Parts/Brackets --wait --format csv --headers
pcli2 report download --id <ID> --format xlsx
Options:
| Flag | Meaning |
|---|---|
--folder-path P | A folder to search, subfolders included (repeatable). / means the root's own assets (see --include-home). |
--exclude-folder-path P | A subfolder of a searched folder to leave out, with its own subfolders (repeatable). |
--extension E | Only assets with this file extension, e.g. stl (repeatable). |
--min-threshold N / --max-threshold N | Similarity range, 0 to 100 (default 80 to 100). |
--exclude-assemblies | Leave assemblies out of the groups. |
--exclude-exact-duplicates | Leave out 100% matches that share a file name. |
--include-home | Include the root folder's own assets. |
--wait | Poll until the report is COMPLETED, FAILED or CANCELLED, printing progress on stderr. |
--poll-interval S | Seconds between polls (default 5). |
With --wait, one failed poll is retried and a credential failure stops the
command at once, as with every other long-running pcli2 command. A report that
ended FAILED or CANCELLED exits 69 and points at report diagnose.
Exit Codes
| Code | When |
|---|---|
| 0 | Done; for diagnose, found and not-found alike |
| 64 | Download of a FAILED or CANCELLED report; bad thresholds; a refused confirmation prompt |
| 67 | The report id does not exist |
| 68 | diagnose on a deployment without failure log search |
| 69 | Download of a report still running; create --wait that ended FAILED or CANCELLED |
Downloading and Uploading Folders
folder download, folder upload and folder thumbnail work on every asset of a
folder and its subfolders (--folder-path / is the whole tenant). They run four
items at a time by default, show progress bars in a terminal, and end with a
summary on stderr.
Without --continue-on-error the first failure stops the run: items that had not
started are counted as "Not attempted". With it, every item is tried and the run
still exits 69 when any failed. folder upload refuses files that already exist
in the destination before uploading anything (pass --skip-existing to skip them
instead). folder download downloads finished assets and assemblies waiting for
a missing part, and lists the assets it left out because they were still
processing or had failed.
On a tenant with an asset limit, folder upload and asset create-batch warn
before uploading when the files would bring the tenant to the point where the
web UI starts warning (85% of the limit on every tenant seen so far), or past
the limit. The warning never stops the upload. Most tenants have no limit and
are not checked.
Speed and Rate Limits
Optimize operations for large datasets:
# Concurrent downloads (faster for many files)
pcli2 folder download --folder-path "/Home/LargeFolder/" --concurrent 5 --progress
# Add delays to prevent rate limiting
pcli2 folder download --folder-path "/Home/Folder/" --delay 2
# Continue on errors
pcli2 folder download --folder-path "/Home/Folder/" --continue-on-error
# Continue past unresolvable asset paths in a metadata batch
pcli2 asset metadata create-batch --input "metadata.csv" --continue-on-error
# Download thumbnails for all assets in a folder
pcli2 folder thumbnail --folder-path "/Home/Folder/" --progress --concurrent 3
Resuming Interrupted Runs
Every long-running command can pick up where it stopped:
# Download: skip files that already exist in the destination
pcli2 folder download --folder-path "/Home/LargeFolder/" --resume --progress
# Upload: skip files whose name is already in the target folder
pcli2 folder upload --input ./parts --folder-path "/Home/Parts" --skip-existing
pcli2 asset create-batch --input "parts/*.stl" --folder-path "/Home/Parts" --skip-existing
# Folder match: record each completed search, re-run the same command to continue
pcli2 folder geometric-match --folder-path "/Home/Parts" --recursive \
--checkpoint parts-match.jsonl --format csv --headers > matches.csv
With --checkpoint FILE a folder match appends each asset's result to FILE the
moment its search finishes. If the run is interrupted, re-running the same
command with the same file reuses the recorded results and searches only the
assets that are left. The file is tied to the exact run (search type, tenant,
folders, threshold, --recursive, --exclusive, --limit); a file from a
different run is refused rather than mixed in. It is deleted once the report has
been written.
The Summary at the End
When using folder download and upload commands, you'll receive detailed statistics reports:
Download Statistics Report:
📊 Download Statistics Report
===========================
✅ Successfully downloaded: 125 assets
⏭️ Skipped (already existed): 75 assets
❌ Failed downloads: 2 assets
📁 Total assets processed: 202 assets
⏳ Operation completed successfully!
Upload Statistics Report:
📊 Upload Statistics Report
==========================
✅ Successfully uploaded: 150 assets
⏭️ Skipped (already existed): 0 assets
❌ Failed uploads: 1 asset
📁 Total assets processed: 151 assets
⏳ Operation completed successfully!
Scripting and Automation
PCLI2 is designed to work well in shell scripts, cron jobs, and CI/CD pipelines. This page collects the features that matter when no human is watching the terminal.
Table of Contents
- Machine-Friendly Output
- Skipping Prompts
- Dry Run Mode
- Exit Codes
- Verbosity Control
- Automatic Retries
- Update Notifications
- CI/CD Example
Machine-Friendly Output
Colors, spinners, and progress bars are shown only when the output is a terminal. When you pipe or redirect output, you get clean text automatically:
# Clean JSON, no ANSI escape codes
pcli2 asset list --folder-path "/Home/Models/" --format json | jq '.[].name'
# CSV with headers for spreadsheets
pcli2 asset list --folder-path "/Home/Models/" --format csv --headers > assets.csv
To disable colors explicitly, use the --no-color flag or set the
NO_COLOR (or PCLI2_NO_COLOR) environment variable.
The same rules apply to diagnostics on stderr: warnings and --verbose
logs captured with 2> warnings.log are plain text with no ANSI escape
codes, so they can be grepped and parsed directly.
Tables and Columns
In a terminal, a command that can print CSV shows a table when you do not ask
for a format; the moment its output goes to a pipe or a file it is JSON, exactly
as before. Ask for either explicitly with --format table or --format json.
--columns keeps only the named CSV or table columns, in the order given
(matched by header name, in any letter case). An unknown name is an error
(exit 64) that lists the available columns:
pcli2 asset list --folder-path /Home/Parts --format csv --columns path,uuid
pcli2 asset list --folder-path /Home/Parts --format table --columns name,state
Pipelines: grep, jq and NuShell
Chain commands with other tools. In JSON output, metadata values are strings
("Weight": "12.5"); convert them before comparing numbers.
# Filter assets with grep
pcli2 asset list --folder-path "/Home/Models/" --format csv | grep "bearing"
# Process with jq: paths of files over 10 kB
pcli2 asset list --folder-path "/Home/Models/" --format json | jq -r '.[] | select((.file_size // 0) > 10000) | .path'
# jq on metadata: assets weighing 5 or more
pcli2 asset list --folder-path "/Home/Models/" --metadata --format json | jq -r '.[] | select((.metadata.Weight // "0" | tonumber) >= 5) | .path'
# Count results
pcli2 asset list --folder-path "/Home/Models/" --format csv | wc -l
# NuShell: assets weighing between 5 and 50
pcli2 asset list --folder-path "/Home/MyFolder" --metadata --format json | nu --stdin -c 'from json | where {|a| ($a.metadata.Weight? | default "0" | into float) >= 5.0 and ($a.metadata.Weight? | default "0" | into float) <= 50.0 } | select name path'
# NuShell: count and average weight per material
pcli2 asset list --folder-path "/Home/Inventory" --metadata --format json | nu --stdin -c 'from json | where {|a| $a.metadata.Material? != null } | insert material {|a| $a.metadata.Material } | insert weight {|a| $a.metadata.Weight? | default "0" | into float } | group-by material --to-table | each {|g| {material: $g.material, count: ($g.items | length), avg_weight: ($g.items.weight | math avg)} }'
Safe CSV for Spreadsheets
A CSV cell that starts with =, +, - or @ is evaluated as a formula by
Excel, LibreOffice and Google Sheets when the file is opened, and asset names
and metadata values come from whoever uploaded them. With --safe-csv (or
PCLI2_SAFE_CSV=1) such cells are written with a leading single quote, which
spreadsheets show as plain text. Values that are numbers, such as -5, are
left alone. The default is off because the quote is visible to every other
consumer of the file.
pcli2 asset list --folder-path "/Home/Parts" --format csv --headers --safe-csv > parts.csv
Excel workbooks written with --format xls are not affected: their cells are
stored as strings and are never evaluated.
Machine-Readable Errors
With --error-format json (or PCLI2_ERROR_FORMAT=json) everything pcli2
writes to stderr is one JSON object per line: errors, their hints, warnings,
--verbose log lines and the --stats summary. The last object of a failed
run carries the exit code and its class:
$ pcli2 --error-format json asset delete --path /Home/Parts/nope.stl
{"level":"ERROR","code":67,"kind":"not_found","message":"API error: Path not found: /Home/Parts/nope.stl"}
$ echo $?
67
| Field | Meaning |
|---|---|
level | ERROR, WARN, INFO or DEBUG, matching the log lines |
code | The process exit code, on the final error object |
kind | The failure class: usage, data, no_input, not_found, unavailable, temp_fail, software, os, config, auth, network, api |
message | The same text the human-readable error would show |
hint | What to do about it, when pcli2 knows |
http_status | The HTTP status behind an API error, when there is one |
steps | Remediation steps, on errors that list them |
Progress bars and the upload/download statistics reports are not JSON; leave
--progress off in scripts that parse stderr.
# Read the exit code and message of a failed run
if ! out=$(pcli2 --error-format json asset list --folder-path "/Nope" 2>&1 >/dev/null); then
echo "$out" | tail -n 1 | jq -r '"\(.kind): \(.message)"'
fi
Skipping Prompts
Destructive commands ask for confirmation when run interactively. In
scripts, pass --yes:
pcli2 folder delete --folder-path "/Home/Scratch/" --force --yes
pcli2 cache clear --yes
A prompt that cannot be shown is refused rather than answered for you: when
stdin is not a terminal, or --no-input (or PCLI2_NO_INPUT=1) is set, a
command that would have to ask exits 64 and says which flag to pass instead.
tenant use and env use without --name fail the same way instead of
showing a menu nobody can answer. Set PCLI2_NO_INPUT=1 in CI so a forgotten
--yes fails fast rather than hanging on a prompt.
For a non-interactive login, put the credentials in PCLI2_CLIENT_ID and
PCLI2_CLIENT_SECRET (your CI system's secret store is the right source).
--client-id and --client-secret work too, but a secret on the command line
ends up in shell history and in process listings:
export PCLI2_CLIENT_ID="$PHYSNA_CLIENT_ID"
export PCLI2_CLIENT_SECRET="$PHYSNA_CLIENT_SECRET"
pcli2 auth login
Choosing the Tenant and Environment per Command
--tenant (or PCLI2_TENANT) and --env (or PCLI2_ENV) apply to one
command and change nothing on disk, unlike pcli2 tenant use and
pcli2 env use. Scripts that run side by side against different tenants or
environments should use them instead of switching the saved defaults:
PCLI2_ENV=staging pcli2 asset list --folder-path /Home/Parts --format csv
pcli2 --env production asset list --folder-path /Home/Parts --tenant acme --format csv
Calling Any API Endpoint
pcli2 api sends a request to any endpoint of the Physna API, including the
ones no pcli2 command covers yet, with pcli2's login, token renewal, retries and
tenant. {tenantId} in the path is replaced with the active tenant (or the one
named with --tenant):
# The first page of the active tenant's folders
pcli2 api /tenants/{tenantId}/folders
# Every page, merged into one list
pcli2 api /tenants/{tenantId}/folders --paginate
# A POST: -F adds a JSON field (read as JSON when it parses), -f a string field
pcli2 api /tenants/{tenantId}/assets/existing-paths -F paths='["/Home/a.stl"]'
# A body from a file (or - for standard input), with an explicit method
pcli2 api /tenants/{tenantId}/reports/duplication -X POST --input request.json
The response body is printed as it came (pretty-printed in a terminal). A non-2xx answer is an error with the server's message and the usual exit code.
Dry Run Mode
Preview destructive or bulk operations without changing anything on the
server. Supported by asset delete, folder delete, report delete,
tenant metadata delete, tenant metadata rename, asset create,
asset create-batch, folder upload, asset move and
asset resolve-dependency:
# List exactly which files a batch upload would send, and where
pcli2 asset create-batch --input "build/*.stl" --folder-path "/Home/CI Builds/" --dry-run
# Confirm what a forced folder delete would remove
pcli2 folder delete --folder-path "/Home/Old Projects/" --force --dry-run
Exit Codes
PCLI2 uses distinct exit codes (the 64-78 range is modelled on BSD
sysexits.h) so scripts can react to specific failure classes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 64 | Command line usage error |
| 65 | Data format error |
| 66 | Cannot open input file |
| 67 | Resource not found |
| 68 | Service unavailable |
| 69 | Temporary failure |
| 70 | Internal software error |
| 71 | Operating system error |
| 78 | Configuration error |
| 100 | Authentication error |
| 101 | Network communication error |
| 102 | Remote API error |
A usage error rejected by the argument parser also exits 64. Batch commands that
finished with some items failed, and folder matches whose report would be
incomplete, exit 69, as does a request the server kept rejecting with 429 (rate
limited) or a 5xx after every retry: try again later. A closed output pipe
(pcli2 ... | head) is not an error and exits 0. asset diagnose exits 68 on a deployment without failure
log search (pcli2 doctor shows that up front on its diagnostics line); a
not-found answer is printed and exits 0, since it is an answer.
pcli2 asset get --path "/Home/Models/part.stl" --format json
case $? in
0) echo "found" ;;
100) pcli2 auth login ;;
101) echo "network problem, try again later" ;;
*) echo "failed" ;;
esac
Verbosity Control
The global --quiet flag limits diagnostics to errors; --verbose (-v)
enables debug-level logging. Both work on every command and take
precedence over the PCLI2_LOG_LEVEL and RUST_LOG environment
variables:
pcli2 --quiet asset create-batch --input "build/*.stl" --folder-path "/Home/CI Builds/"
PCLI2_LOG_LEVEL=trace pcli2 folder list
Automatic Retries
Transient failures (network timeouts, connection errors, and HTTP
408/429/502/503/504 responses) are retried automatically with exponential
backoff, honoring the server's Retry-After header. The default is 2
retries; tune it with PCLI2_MAX_RETRIES (0 disables retries):
PCLI2_MAX_RETRIES=5 pcli2 folder download --folder-path "/Home/Models/" --output ./downloads
The request timeout defaults to 30 minutes (large model files take that
long to transfer). Lower it with PCLI2_TIMEOUT (seconds) if you prefer
fast failures over patience:
PCLI2_TIMEOUT=120 pcli2 asset list --folder-path "/Home/Models/"
Note that timeouts abort-and-retry only read requests (GETs); a timed-out write is never retried automatically because the server may have already processed it.
Resuming Interrupted Runs
Long runs in a script should be written so that a retry does not redo finished work:
# Downloads skip files already on disk
pcli2 folder download --folder-path "/Home/Parts" --output ./parts --resume
# Uploads skip files whose name is already in the folder
pcli2 asset create-batch --input "parts/*.stl" --folder-path "/Home/Parts" --skip-existing
# Folder matches record each completed search; the same command continues the run
pcli2 folder geometric-match --folder-path "/Home/Parts" --recursive \
--checkpoint parts.jsonl --format csv --headers > parts.csv
The checkpoint file is removed when the report is written, so a loop that retries until the command exits 0 needs no cleanup of its own.
Request Statistics
Add --stats to any command to get one line on stderr at exit with the number
of API requests made, how many were retried, how many token renewals happened,
and the elapsed time. It is the quickest way to see whether a batch is doing
more work than it should:
pcli2 --stats asset metadata create-batch --input metadata.csv
# 📊 5,102 API request(s), 2 retried, 1 token renewal(s) in 3m41s
Checking the Setup
pcli2 doctor prints the local state in one screen (binary and PATH,
configuration, environment, credentials, token expiry, tenant, caches, API and
auth-server reachability, whether failure diagnostics are available for
asset diagnose, update state) and exits non-zero when something is
wrong: 78 for a local problem, 68 when a server cannot be reached.
--format json makes it machine-readable.
Update Notifications
In interactive terminal sessions, PCLI2 prints a one-line hint on stderr
when a newer release is available (checked at most once per day). The
check never runs in CI (detected via the CI environment variable) or
when output is redirected. To opt out entirely:
export PCLI2_NO_UPDATE_CHECK=1
CI/CD Example
A GitHub Actions job that uploads build artifacts to Physna:
jobs:
upload-models:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install pcli2
run: curl --proto '=https' --tlsv1.2 -LsSf https://github.com/jchultarsky101/pcli2/releases/latest/download/pcli2-installer.sh | sh
- name: Authenticate
run: pcli2 auth login
env:
PCLI2_CLIENT_ID: ${{ secrets.PHYSNA_CLIENT_ID }}
PCLI2_CLIENT_SECRET: ${{ secrets.PHYSNA_CLIENT_SECRET }}
- name: Upload models
run: |
pcli2 tenant use --name my-tenant
pcli2 asset create-batch --input "build/*.stl" \
--folder-path "/Home/CI Builds/" --quiet --format json
Command Reference
An overview of every command and its aliases. pcli2 <command> --help shows each
command's flags and examples in full.
Aliases
Quick reference for all available command aliases:
Tenant Commands
| Full Command | Alias |
|---|---|
pcli2 tenant list | pcli2 tenant ls |
pcli2 tenant use | pcli2 tenant select |
pcli2 tenant get | pcli2 tenant current |
pcli2 tenant clear | pcli2 tenant unset |
pcli2 tenant metadata list | pcli2 tenant metadata ls |
Folder Commands
| Full Command | Alias |
|---|---|
pcli2 folder list | pcli2 folder ls |
pcli2 folder delete | pcli2 folder rm |
pcli2 folder get | pcli2 folder cat |
pcli2 folder create | pcli2 folder add |
pcli2 folder move | pcli2 folder mv |
pcli2 folder rename | pcli2 folder ren |
pcli2 folder resolve | pcli2 folder res |
pcli2 folder description clear | pcli2 folder description rm |
pcli2 folder download | pcli2 folder dl |
pcli2 folder geometric-match | pcli2 folder geometric-search, pcli2 folder gm |
pcli2 folder part-match | pcli2 folder part-search, pcli2 folder pm |
pcli2 folder visual-match | pcli2 folder visual-search, pcli2 folder vm |
Asset Commands
| Full Command | Alias |
|---|---|
pcli2 asset list | pcli2 asset ls |
pcli2 asset delete | pcli2 asset rm |
pcli2 asset get | pcli2 asset cat |
pcli2 asset create | pcli2 asset upload |
pcli2 asset create-batch | pcli2 asset upload-batch |
pcli2 asset download | pcli2 asset dl |
pcli2 asset dependencies | pcli2 asset deps |
pcli2 asset dependency-diff | pcli2 asset deps-diff |
pcli2 asset thumbnail | pcli2 asset thumb |
pcli2 asset geometric-match | pcli2 asset geometric-search, pcli2 asset gm |
pcli2 asset part-match | pcli2 asset part-search, pcli2 asset pm |
pcli2 asset visual-match | pcli2 asset visual-search, pcli2 asset vm |
pcli2 asset text-match | pcli2 asset text-search, pcli2 asset tm |
pcli2 asset similarity | pcli2 asset match-scores |
pcli2 asset diagnose | pcli2 asset failure, pcli2 asset why |
pcli2 asset move | pcli2 asset mv |
pcli2 asset resolve-dependency | pcli2 asset resolve-dep |
pcli2 asset metadata create | pcli2 asset metadata update |
pcli2 asset metadata create-batch | pcli2 asset metadata update-batch |
pcli2 asset metadata delete | pcli2 asset metadata rm |
Authentication Commands
| Full Command | Alias |
|---|---|
pcli2 auth | pcli2 a |
pcli2 auth login | pcli2 auth in |
pcli2 auth logout | pcli2 auth out |
pcli2 auth get | pcli2 auth token |
pcli2 auth clear-token | pcli2 auth clear |
pcli2 auth expiration | pcli2 auth exp |
Environment Commands
| Full Command | Alias |
|---|---|
pcli2 environment | pcli2 env |
pcli2 environment list | pcli2 env ls |
pcli2 environment remove | pcli2 env rm |
Catalog Commands
| Full Command | Alias |
|---|---|
pcli2 catalog list | pcli2 catalog ls |
pcli2 catalog geometric-match | pcli2 catalog gm |
pcli2 catalog part-match | pcli2 catalog pm |
pcli2 catalog visual-match | pcli2 catalog vm |
Report Commands
| Full Command | Alias |
|---|---|
pcli2 report list | pcli2 report ls |
pcli2 report download | pcli2 report dl |
pcli2 report diagnose | pcli2 report why |
pcli2 report delete | pcli2 report rm |
Other Commands
| Full Command | Alias |
|---|---|
pcli2 user list | pcli2 user ls |
pcli2 cache clear | pcli2 cache clean |
Commands
Asset Commands
Manage individual assets in your Physna tenant.
pcli2 asset create # Upload a file as an asset
pcli2 asset create-batch # Upload multiple files as assets using glob patterns (--skip-existing to re-run)
pcli2 asset list # List assets in a folder with optional recursive listing (--recursive)
pcli2 asset inventory # List complete inventory of all assets in the tenant
pcli2 asset counts # Show asset health report with counts by state, type, and structure
pcli2 asset get # Get asset details (--uuid may be repeated to fetch several in one request)
pcli2 asset download # Download an asset
pcli2 asset delete # Delete an asset
pcli2 asset move # Move an asset to another folder, or to the root (--folder-path /)
pcli2 asset dependencies # Get dependencies for an asset
pcli2 asset dependency-diff # Diff the dependency trees of two assets
pcli2 asset resolve-dependency # Link a missing dependency of an assembly to an existing asset
pcli2 asset geometric-match # Find geometrically similar assets
pcli2 asset part-match # Find part matches for an asset
pcli2 asset visual-match # Find visually similar assets (--limit N, default 100; --threshold N size filter, default 80)
pcli2 asset text-match # Find assets using text search (--limit N, default 1000; warns on stderr when more matches exist)
pcli2 asset similarity # Match scores between two specific assets (--reference-* and --candidate-*)
pcli2 asset reprocess # Reprocess an asset to refresh its analysis
pcli2 asset diagnose # Explain why an asset failed to process (server-side failure diagnostics)
pcli2 asset thumbnail # Download asset thumbnail
pcli2 asset metadata # Manage asset metadata (get, create, create-batch, delete, inference)
Asset List Command
The asset list command lists assets in a folder with various filtering and formatting options.
# List assets in a specific folder
pcli2 asset list --folder-path "/Home/Models/"
# List assets recursively (including all subfolders)
pcli2 asset list --folder-path "/Home/Models/" --recursive
# Output in CSV format with headers
pcli2 asset list --folder-path "/Home/Models/" --format csv --headers
# Include metadata in JSON output
pcli2 asset list --folder-path "/Home/Models/" --format json --metadata
# Force refresh folder cache before listing (useful after folder changes)
pcli2 asset list --reload --folder-path "/Home/Models/" --format csv
Asset Inventory and Counts Commands
The asset inventory and asset counts commands both retrieve all assets across the entire tenant (not scoped to a folder). They differ in output:
asset inventoryoutputs the full list of assets (same format asasset list)asset countsoutputs an aggregated health report with counts by processing state, file type, and structure
# Full inventory in CSV with headers
pcli2 asset inventory --format csv --headers
# Full inventory in JSON with metadata
pcli2 asset inventory --format json --metadata
# Asset health report in JSON
pcli2 asset counts --format json
# Asset health report in CSV
pcli2 asset counts --format csv --headers
Asset Dependency Diff Command
The asset dependency-diff command (alias deps-diff) compares the recursive dependency trees of two assemblies — a reference and a candidate — and reports which parts differ between them.
Each asset is identified by either its UUID or its path, consistent with other asset commands. Provide exactly one identifier per side:
--reference-uuidor--reference-path--candidate-uuidor--candidate-path
The comparison is structural: the two trees are walked in parallel and their nodes are matched by filename. It is presence-only — a part is reported as present in both (=), only in the reference (-), or only in the candidate (+); occurrence counts are not compared. If a whole subassembly is present on only one side, its entire subtree is marked accordingly.
Supported output formats: tree (default view of the merged diff), json, and csv.
# Diff two assemblies by path, rendered as a tree
pcli2 asset dependency-diff \
--reference-path /Parts/AssemblyA.SLDASM \
--candidate-path /Parts/AssemblyB.SLDASM \
--format tree
# Diff by UUID, as pretty JSON
pcli2 asset deps-diff \
--reference-uuid 00000000-0000-0000-0000-000000000001 \
--candidate-uuid 00000000-0000-0000-0000-000000000002 \
--format json --pretty
# Diff as CSV with headers (STATUS, ASSEMBLY_PATH, FILENAME, ASSET_UUID, ASSET_STATE)
pcli2 asset deps-diff \
--reference-path /Parts/AssemblyA.SLDASM \
--candidate-path /Parts/AssemblyB.SLDASM \
--format csv --headers
Example tree output:
dependency diff: reference `/Parts/AssemblyA.SLDASM` vs candidate `/Parts/AssemblyB.SLDASM`
├─ (=) gearbox.sldasm [finished] (…)
│ ├─ (=) shaft.stl [finished] (…)
│ ├─ (-) bearing-v1.stl [finished] (…)
│ └─ (+) bearing-v2.stl [finished] (…)
├─ (-) bracket-old.stl [finished] (…)
└─ (+) bracket-new.stl [finished] (…)
Legend: (=) in both (-) only in reference (+) only in candidate
Summary: 2 common, 2 only in reference, 2 only in candidate
If either asset cannot be resolved, the command reports which input (reference or candidate) failed. An asset that is not an assembly is treated as having no dependencies.
Asset Metadata Commands
Manage custom properties for assets.
pcli2 asset metadata get # Get metadata for an asset
pcli2 asset metadata create # Add metadata to an asset
pcli2 asset metadata delete # Delete specific metadata fields from an asset
pcli2 asset metadata create-batch # Create metadata for multiple assets from a CSV file
pcli2 asset metadata inference # Apply metadata from a reference asset to geometrically similar assets
Asset Metadata Create-Batch CSV Formats
The asset metadata create-batch command accepts two CSV layouts. The layout is auto-detected from the header row (any column starting with metadata: selects the UI format), or can be forced with --csv-format classic|ui.
Classic (vertical) format — one row per asset+field combination:
ASSET_PATH,NAME,VALUE,TYPE
/Home/Folder/Model1.stl,Material,Steel,text
/Home/Folder/Model1.stl,Weight,15.5,number
/Home/Folder/Model2.ipt,Inventory Qty,42,number
/Home/Folder/Model2.ipt,Supplier Link,https://example.com/,url
- The first row must contain the headers
ASSET_PATH,NAME,VALUE, optionally followed byTYPE - Each row represents a single metadata field assignment for an asset
- If an asset has multiple metadata fields to update, include multiple rows with the same
ASSET_PATHbut differentNAMEandVALUEcombinations TYPEis optional (defaulttext; one oftext,number,boolean,url) and only sets the type used when registering a new field — for an existing field, its registered type is authoritative andTYPEis ignored- A leading
/HomeinASSET_PATH(Physna's name for the root folder) is treated as the root, so/Home/NX/part.prtandNX/part.prtrefer to the same asset
UI (horizontal) format — one row per asset, as exported by the Physna web UI's bulk metadata upload:
path,id,metadata:Material,metadata:Color
/Home/Folder/Model1.stl,,Steel,Blue
/Home/Folder/Model2.ipt,123e4567-e89b-12d3-a456-426614174000,Aluminum,Red
pathis the asset path; the optionalidcolumn holds the asset UUID and takes precedence over the path when present- Each
metadata:<field name>column sets one metadata field (the prefix is stripped) - Unrecognized columns are ignored with a warning
In both formats, empty values are skipped by default (existing metadata is left untouched). Pass --delete-if-empty to instead delete a metadata field from the asset when the file contains an empty value for it.
Automatic type coercion: because a CSV cell is text, each value is coerced to the field's registered type before upload — a number field receives 18 (not "18"), a boolean field accepts true/false/yes/no/1/0, and text/url fields store the value as a string. A value that cannot be represented as the field's type (e.g. N/A for a number field) is a type conflict and is reported as an error.
General requirements (both formats):
- The file must be UTF-8 encoded
- Values containing commas, quotes, or newlines must be enclosed in double quotes
- Empty rows will be ignored
Error Handling:
By default, the batch stops on the first error and reports how many assets were processed successfully. Pass --continue-on-error to skip the offending asset — whether its ASSET_PATH cannot be resolved or its metadata update fails (including a type conflict) — and continue with the remaining assets. Authentication failures always terminate the batch regardless of the flag.
To generate a starting CSV of the fields already registered in the tenant (with their types), use pcli2 tenant metadata list --format csv --headers (see Tenant Commands).
Folder Commands
Manage folder structures and bulk operations.
pcli2 folder list # List folder structure (defaults to root path if no path/UUID specified)
pcli2 folder create # Create a new folder (--description TEXT, optional)
pcli2 folder description # Show, set or clear a folder's description (get / set --text / clear)
pcli2 folder get # Get folder details
pcli2 folder delete # Delete a folder
pcli2 folder rename # Rename a folder
pcli2 folder move # Move a folder to a new parent folder
pcli2 folder resolve # Resolve a folder path to its UUID
pcli2 folder download # Download all assets in a folder (--resume skips files already on disk)
pcli2 folder upload # Upload all assets from a local directory to a Physna folder (--skip-existing)
pcli2 folder dependencies # Get dependencies for all assembly assets in folder
pcli2 folder geometric-match # Find geometrically similar assets for all assets in folder (--checkpoint FILE to resume)
pcli2 folder part-match # Find part matches for all assets in folder (--checkpoint FILE to resume)
pcli2 folder visual-match # Find visually similar assets for all assets in folder (--limit N, default 100; --threshold N size filter, default 80)
pcli2 folder thumbnail # Download thumbnails for all assets in a folder
Important Note: Folder paths are case-insensitive. You can use any capitalization when specifying folder paths (e.g., /Home/Models, /home/models, /HOME/MODELS all refer to the same folder). This matches the behavior of Windows file systems and provides a more user-friendly experience.
Folder Descriptions
A folder can carry an optional description of up to 255 characters, the one
the web app shows. folder get and folder list include it as description
in their JSON output when a folder has one; their CSV columns are unchanged.
folder list reads the cached folder tree, so a description changed in the web app
shows there once the cache refreshes (or at once with --reload); set and clear
refresh it themselves.
# Set or replace a description (surrounding spaces are dropped)
pcli2 folder description set --folder-path /Projects/Rail --text "Rail car parts, 2026 program"
# Print it, alone on a line (nothing when the folder has none)
pcli2 folder description get --folder-path /Projects/Rail
# Remove it
pcli2 folder description clear --folder-path /Projects/Rail
# Give a new folder a description when creating it
pcli2 folder create --name Rail --parent-folder-path /Projects --description "Rail car parts"
set and clear print nothing on success. An empty description or one over
255 characters is refused with exit code 64 before anything is sent.
Folder Resolve Command
The folder resolve command resolves a folder path to its UUID, which can be useful for scripting or debugging.
# Resolve a folder path to UUID
pcli2 folder resolve --folder-path "/Home/MyFolder"
# Force refresh folder cache before resolving (useful if folder was recently recreated)
pcli2 folder resolve --reload --folder-path "/Home/MyFolder"
Folder List Command
The folder list command allows you to list folders in your Physna tenant. When no folder path or UUID is specified, it defaults to listing the root folder.
# List all folders in the root directory (default behavior)
pcli2 folder list
# List folders in a specific path
pcli2 folder list --folder-path "/Home/MyFolder"
# List folders using folder UUID
pcli2 folder list --folder-uuid 123e4567-e89b-12d3-a456-426614174000
# List folders with specific output format
pcli2 folder list --format tree
Key Features:
- Default Root Path: When no folder identifier is provided, defaults to the root path (
/) - Mutual Exclusivity: You can specify either
--folder-pathor--folder-uuid, but not both - Flexible Output: Supports JSON, CSV, and tree formats
- Folder Hierarchy: Shows the complete folder structure when using tree format
- Cache Refresh: Use
--reloadflag to force refresh of folder cache before listing
# Force refresh folder cache before listing (useful after folder changes)
pcli2 folder list --reload
# Combine with other flags
pcli2 folder list --reload --format tree
Tenant Commands
Manage tenant-level operations.
pcli2 tenant list # List all tenants
pcli2 tenant get # Get the active tenant (alias: current)
pcli2 tenant use # Set the active tenant
pcli2 tenant clear # Clear the active tenant
pcli2 tenant state # Get asset state counts for the current tenant
pcli2 tenant failures # List recent failures (assets, reports, part-finder reports), newest first
pcli2 tenant usage # Searches, downloads, active users, ... over a period, plus asset counts by type
pcli2 tenant metadata list # List the tenant's registered metadata fields with their types
pcli2 tenant metadata rename # Rename a field (--name OLD --new-name NEW); values on assets are kept
pcli2 tenant metadata delete # Delete a field (--name NAME); --force also removes its values from every asset
pcli2 tenant metadata assets # List the assets that have a value for a field (--name NAME, --limit N)
pcli2 tenant metadata coverage # How many assets carry any metadata at all (counts and percentage)
pcli2 tenant metadata missing # List the assets with no metadata at all (--folder-path, --extension, --limit)
The tenant metadata list output (CSV) uses the same header as the classic create-batch input (ASSET_PATH,NAME,VALUE,TYPE) with NAME and TYPE filled from the registry and ASSET_PATH/VALUE blank, so it can be saved and turned into a batch-upload template:
pcli2 tenant metadata list --format csv --headers > fields.csv
Tenant Usage
tenant usage reports how much the tenant used Physna over a period of UTC
days: searches (by type), compares, downloads, uploads, reports (by type),
distinct active users and per-feature counts, plus how many assets of each type
the tenant holds now (demo assets uploaded by Physna are not counted). It needs
the tenant admin role.
The period is the last 30 days unless --days N, --from or --to
(YYYY-MM-DD) say otherwise, up to 366 days. The CSV and table output has one
CATEGORY,NAME,COUNT row per number, so a count Physna adds later arrives as a
new row, not a new column; --daily prints one row per day instead.
On a tenant with an asset limit, the JSON output also has assetLimit
(limit, warningThresholdPercent and assets, the count that is measured
against the limit), and a warning goes to stderr once the tenant reaches the
threshold.
# The last 30 days
pcli2 tenant usage
# A quarter, as JSON (the API's fields plus from, to and assetTypes)
pcli2 tenant usage --from 2026-07-01 --to 2026-09-30 --format json
# Active users per day over the last week
pcli2 tenant usage --days 7 --daily --format csv --headers --columns DATE,ACTIVE_USERS
# One number in a script: searches in the last 30 days
pcli2 tenant usage --format csv | awk -F, '$1=="activity" && $2=="searches" {print $3}'
Finding Out Why an Asset Failed
tenant state and asset counts say how many assets failed; tenant failures
says which (newest first; the JSON output adds the tenant-wide totals and
newest-failure time per kind, and lastAttempt on a failure that failed again
after a self-service retry), and
asset diagnose asks the server why. The server searches its ingestion logs
on demand, so the answer is only as durable as log retention.
# The failed assets, newest first (--kind report / part-finder-report for the others)
pcli2 tenant failures --kind asset --format csv --headers
# Why one of them failed, by UUID from that listing or by path
pcli2 asset diagnose --uuid 5db69606-661e-4019-a9b4-a4d122fc0f9e
{
"assetPath": "/Home/Rail/04_Automatic_drain_cock_module.step",
"assetUuid": "5db69606-661e-4019-a9b4-a4d122fc0f9e",
"assetState": "failed",
"status": "found",
"kind": "internal",
"summary": "Processing failed inside Physna.",
"traceId": "d55c845b-80f1-44fb-95df-256aebf7bf3c",
"occurredAt": "2026-09-07T14:02:02.356Z"
}
kind: usermeans the failure is yours to fix andsummarysays what (an unsupported format, for example).kind: internalmeans it failed on Physna's side: quote thetraceIdto support.status: not-found(exit 0) means the asset is not failed, or the log entry has aged out; a note on stderr says which. Reprocessing produces a fresh entry if the asset fails again.- On a deployment without failure log search the command exits 68.
pcli2 doctorhas adiagnosticsline that says up front whether the lookup is available.
CSV columns: ASSET_PATH,ASSET_STATE,STATUS,KIND,SUMMARY,TRACE_ID,OCCURRED_AT,ASSET_UUID.
Report Commands
Reports (duplication, simplification, custom) are jobs that run on the server and then hold data you can download. See the Reports chapter for details.
pcli2 report list # List the tenant's reports, newest first (--type, --status, --limit)
pcli2 report get # Show one report: status, progress, settings (--id)
pcli2 report download # Download a COMPLETED report's data (--id, --format csv|xlsx, -o PATH)
pcli2 report diagnose # Explain why a report failed, like 'asset diagnose' (--id)
pcli2 report delete # Delete a report; asks for confirmation unless --yes (--id, --dry-run)
pcli2 report create # Start a duplication report over folders; --wait follows it to the end
# Start a duplication report over a folder, wait for it, then download the data as Excel
pcli2 report create --name "Brackets" --folder-path "/Home/Parts/Brackets" --wait --format csv --headers
pcli2 report download --id <ID> --format xlsx -o brackets.xlsx
# Why did a report fail? (tenant failures lists the failed ones)
pcli2 report diagnose --id <ID>
Catalog Commands
Match an asset from your tenant against a catalog, such as a supplier catalog. Physna enables catalogs per customer; --in accepts only the catalogs catalog list shows. See the Catalog Search chapter for details.
pcli2 catalog list # The catalogs you can search
pcli2 catalog geometric-match # Geometrically similar catalog assets (--path|--uuid, --in, --threshold, --limit)
pcli2 catalog part-match # Part search in a catalog (same options)
pcli2 catalog visual-match # Visually similar catalog assets (--threshold is a size tolerance)
# Supplier parts that look like a bracket, as CSV
pcli2 catalog visual-match --path /Home/Parts/bracket.stl --limit 20 --format csv --headers
Authentication Commands
Manage authentication with your Physna tenant.
pcli2 auth login # Authenticate with Physna using client credentials
pcli2 auth logout # Logout and clear session
pcli2 auth get # Get current access token
pcli2 auth clear-token # Clear the cached access token
pcli2 auth expiration # Show token expiration time
Configuration Commands
Manage PCLI2 configuration settings.
pcli2 config get path # Print the path of the configuration file
pcli2 config validate # Check the configuration and credentials (--api also calls the API)
pcli2 config export # Export configuration to file (-o/--output)
pcli2 config import # Import configuration from file (-i/--input)
pcli2 env ... # Manage environment configurations (below)
Environment Configuration Commands
Manage multiple Physna environment configurations.
pcli2 env add --name <name> # Add a new environment configuration
pcli2 env add -n <name> # Short form of add with name
pcli2 env use --name <name> # Switch to an environment
pcli2 env use -n <name> # Short form of use with name
pcli2 env remove --name <name> # Remove an environment
pcli2 env remove -n <name> # Short form of remove with name
pcli2 env list # List all environments
pcli2 env reset # Reset all environment configurations
pcli2 env get --name <name> # Get environment details
pcli2 env get -n <name> # Short form of get with name
Each environment remembers the tenant last selected in it. env use makes that
tenant active again; an environment where no tenant was selected yet starts with
none, so a tenant from another environment is never used by mistake.
Other Commands
Additional utility commands.
pcli2 user list # List the users of the active tenant
pcli2 user get <id> # Get one user's details
pcli2 cache clear # Clear cached data (all caches, or --folder / --metadata / --tenant)
pcli2 completions # Generate shell completions for various shells
pcli2 man # Generate man pages for all commands
pcli2 doctor # Check the local setup: binary, configuration, credentials, token, tenant, caches, connectivity
Cache Management Command
The cache command provides tools for managing PCLI2's local cache. Caching improves performance by storing folder hierarchies, metadata definitions, and tenant lists locally, but can sometimes contain stale data.
# Clear all caches (folder, metadata, and tenant)
pcli2 cache clear
# Clear all caches without confirmation prompt (useful for scripts)
pcli2 cache clear --yes
# Clear specific cache types
pcli2 cache clear --folder # Clear only folder hierarchy cache
pcli2 cache clear --metadata # Clear only metadata field cache
pcli2 cache clear --tenant # Clear only tenant list cache
# Combine flags to clear multiple specific caches
pcli2 cache clear --folder --metadata --yes
# Use the alias 'clean'
pcli2 cache clean --yes
When to clear the cache:
- After deleting and recreating folders with the same name
- When folder paths return unexpected results
- After making bulk changes to folder structure
- When troubleshooting "folder not found" errors
- Periodically to ensure fresh data from the API
Note: The --reload flag on commands like folder list, folder resolve, and asset list provides a convenient way to refresh the folder cache for a single operation without clearing all caches.
# Example: List assets with fresh folder data
pcli2 asset list --reload --folder-path "/Home/Models/" --format csv
Shell Completions
Generate shell completions for various shells to enable tab completion for PCLI2 commands.
# Generate shell completions for various shells
pcli2 completions bash # Generate bash completions
pcli2 completions zsh # Generate zsh completions
pcli2 completions fish # Generate fish completions
pcli2 completions powershell # Generate PowerShell completions
pcli2 completions elvish # Generate Elvish completions
# Install bash completions (system-wide)
sudo pcli2 completions bash > /etc/bash_completion.d/pcli2
# Or for user-specific installation:
mkdir -p ~/.local/share/bash-completion/completions
pcli2 completions bash > ~/.local/share/bash-completion/completions/pcli2
# Install zsh completions (MacOS/Linux)
# For system-wide installation (requires sudo):
sudo pcli2 completions zsh > /usr/local/share/zsh/site-functions/_pcli2
# For user-specific installation:
mkdir -p ~/.zsh/completions # Standard location (note the 's' at the end)
pcli2 completions zsh > ~/.zsh/completions/_pcli2
# Then add to your ~/.zshrc:
# fpath=(~/.zsh/completions $fpath)
# autoload -U compinit && compinit
# Alternative location (if your system uses the singular form):
# mkdir -p ~/.zsh/completion
# pcli2 completions zsh > ~/.zsh/completion/_pcli2
# Alternative zsh installation method (works on most systems):
pcli2 completions zsh > ~/.zfunc/_pcli2
# Add the following line to your ~/.zshrc:
# fpath+=~/.zfunc; autoload -U compinit && compinit
# Install fish completions
# For user-specific installation:
mkdir -p ~/.config/fish/completions
pcli2 completions fish > ~/.config/fish/completions/pcli2.fish
# Install PowerShell completions
# Add to your PowerShell profile:
pcli2 completions powershell > pcli2-completion.ps1
# Then dot source it in your PowerShell profile:
# . "/path/to/pcli2-completion.ps1"
Man Pages
Generate Unix man pages for PCLI2 and every subcommand (one page per
command, e.g. pcli2-folder-delete.1):
# Install for the current user, then read pages by name.
# Note: `man` only searches the directories listed by `manpath` - it never
# looks in the current directory, so the pages must be installed (or opened
# by path) to be found. If ~/.local/share/man is not in your `manpath`
# output, use a directory that is (e.g. /usr/local/share/man/man1).
mkdir -p ~/.local/share/man/man1
pcli2 man --output-dir ~/.local/share/man/man1
man pcli2
man pcli2-asset-create-batch
# Or read a generated file directly without installing
pcli2 man --output-dir ./man
man ./man/pcli2.1
The pages are a snapshot of the CLI at generation time - re-run the install command after upgrading PCLI2 to refresh them.
Configuration and Environment Variables
PCLI2 reads a small set of environment variables. They are useful for WSL users running a Windows executable, for CI jobs, and for anyone who wants configuration and cache files somewhere other than the platform defaults.
# Where config.yml and the credentials file live
export PCLI2_CONFIG_DIR="/custom/path/to/config"
# Where the folder, tenant and metadata caches live
export PCLI2_CACHE_DIR="/custom/path/to/cache"
# Useful for WSL users running Windows executables
export PCLI2_CONFIG_DIR="/home/$USER/.pcli2"
export PCLI2_CACHE_DIR="/home/$USER/.pcli2/cache"
| Variable | Effect |
|---|---|
PCLI2_CONFIG_DIR | Directory holding config.yml and dev_credentials.json. Default: the platform configuration directory (pcli2 config get path prints it). |
PCLI2_CACHE_DIR | Directory for all cache files. Default: the platform cache directory. |
PCLI2_FORMAT | Default --format when the flag is not given on the command line. |
PCLI2_HEADERS | Default --headers when the flag is not given (1/0, yes/no). |
PCLI2_LOG_LEVEL | Log level: error, warn (default), info, debug, trace. RUST_LOG takes precedence when set. |
PCLI2_TIMEOUT | Total request timeout in seconds (default 1800, to allow very large transfers). Connections time out after 15 seconds and a read after 300 seconds of silence regardless. |
PCLI2_MAX_RETRIES | Retries for transient failures: connection errors, 408/429/503, and 502/504 for requests that are safe to repeat (not uploads or other requests that create something) (default 2; 0 disables). |
PCLI2_NO_COLOR, NO_COLOR | Disable colored output. PCLI2_NO_COLOR follows the pcli2 boolean rule (empty, 0, false, no, off mean off, anything else on); NO_COLOR disables when set to anything non-empty, per no-color.org. |
PCLI2_SAFE_CSV | Guard CSV output against spreadsheet formula injection. Same as --safe-csv. |
PCLI2_NO_INPUT | Never prompt; a command that would need an answer exits 64 instead. Same as --no-input. |
PCLI2_ERROR_FORMAT | text (default) or json. With json, every error, hint and log line on stderr is one JSON object; the last one carries the exit code. Same as --error-format. |
PCLI2_NO_UPDATE_CHECK, CI | Disable the once-a-day new-version hint. |
PCLI2_TENANT | Tenant for this command only, like --tenant. pcli2 tenant use changes the saved default. |
PCLI2_ENV | Environment for this command only, like --env. Nothing is saved, so scripts can target different environments at the same time. |
PCLI2_CLIENT_ID, PCLI2_CLIENT_SECRET | Credentials for auth login without flags or a prompt, for CI. A secret in a variable stays out of shell history and process listings. |
API, UI and authentication URLs are not read from the environment. They belong to
an environment definition: pcli2 env add --name staging --api-url ..., then
pcli2 env use --name staging.
Paths are the same on every platform: /Home/Parts/Bracket.stl, where /Home
(the name Physna shows for the root folder) is optional. Folder path matching is
case-insensitive.
Credentials and Security
Where credentials are kept
pcli2 auth login stores, per environment, the client ID, the client
secret and the current access token in dev_credentials.json, next to
config.yml in the configuration directory (pcli2 config get path prints it;
PCLI2_CONFIG_DIR moves it).
The file is plain text. It is not encrypted; its protection is its permissions:
- On macOS and Linux it is created readable and writable by your account only
(
0600), and an older file with looser permissions is tightened the next time pcli2 reads it. - On Windows it inherits the permissions of the configuration directory, which is in your user profile.
Treat it like an SSH key: do not commit it, do not copy it to shared drives, and do not bake it into container images.
The file is written atomically (a temporary file renamed into place) under a
lock, so several pcli2 runs at once cannot corrupt it. If it ever cannot be read,
pcli2 keeps it as dev_credentials.json.unreadable-<time> rather than
overwriting it; log in again, and recover the old file by hand if you need to.
Building pcli2 from source with --no-default-features --features os-keyring
stores the credentials in the operating system's keychain instead.
Logging out
pcli2 auth logout (and pcli2 auth clear-token) removes the access token
only. The client ID and secret stay, so the next pcli2 auth login does not ask
for them again. To remove the secret from a machine, delete
dev_credentials.json (or the whole configuration directory).
Keeping the secret out of history
pcli2 auth login without flags prompts for the client ID and secret, with the
secret masked. For scripts and CI, put them in PCLI2_CLIENT_ID and
PCLI2_CLIENT_SECRET, filled from your CI system's secret store. Avoid
--client-secret on the command line: it ends up in your shell history and is
visible to other users in process listings while pcli2 runs.
What leaves your machine
- Requests go to the environment's API and authentication URLs (by default
app-api.physna.comand Physna's Amazon Cognito endpoint) over HTTPS. The client secret is only ever sent to the authentication URL. - Once a day, in an interactive terminal, pcli2 asks
api.github.comfor the latest release to tell you about updates. SetPCLI2_NO_UPDATE_CHECK=1to turn that off; it is off in CI. - Nothing else: pcli2 collects no telemetry.
pcli2 env add accepts http:// URLs (for a local test server) but warns, since
the secret and every token would then cross the network unencrypted.
Debug logs (--verbose, PCLI2_LOG_LEVEL=debug) never print the secret or the
access token.
Proxies, Certificates and Timeouts
Proxies
pcli2 uses the standard proxy environment variables:
export HTTPS_PROXY=http://proxy.example.com:3128
export NO_PROXY=localhost,127.0.0.1
pcli2 doctor
HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and NO_PROXY are honoured (upper or
lower case). On macOS and Windows the system proxy settings are used when no
variable is set.
Certificates (corporate TLS inspection)
pcli2 uses the operating system's TLS stack and trust store: the Keychain on
macOS, the certificate store on Windows, OpenSSL and the system CA bundle on
Linux. A corporate root certificate that your browsers already trust is
therefore trusted by pcli2 too; there is nothing to configure in pcli2. On Linux,
add the certificate to the system bundle (update-ca-certificates or
update-ca-trust).
Hosts to allow through a firewall
- The environment's API URL (default
https://app-api.physna.com). - The environment's authentication URL (default Physna's Amazon Cognito
endpoint,
https://physna-app.auth.us-east-2.amazoncognito.com). - Downloads come from the API URL as well.
- Optional:
https://api.github.comfor the once-a-day update hint (PCLI2_NO_UPDATE_CHECK=1turns it off).
pcli2 env get shows the URLs of the active environment.
Timeouts and retries
| Setting | Default | Change with |
|---|---|---|
| Connecting | 15 seconds | - |
| No data received on an open connection | 5 minutes | - |
| Whole request (large uploads and downloads) | 30 minutes | PCLI2_TIMEOUT (seconds) |
| Retries of transient failures | 2 | PCLI2_MAX_RETRIES (0 disables) |
Transient failures are connection errors, rate limiting (429), 408 and 503, and for requests that are safe to repeat also 502 and 504 and timeouts. A download whose connection drops mid-file is started again. A request that keeps failing after the retries exits 69 (try again later); see Scripting and Automation.
pcli2 doctor checks connectivity to both URLs and reports what it found.
Troubleshooting
Start with pcli2 doctor: it checks the binary, the configuration, the
credentials, the token, the tenant, the caches and connectivity in one screen,
and says what to do about anything that is wrong.
By exit code
Every failure exits with a code that names its class (the full table is in Scripting and Automation).
| Code | Meaning | What to do |
|---|---|---|
| 64 | The command line is wrong, or a prompt was needed with --no-input | Read the message; --help on the command shows its flags and examples |
| 65 | Data could not be read (a malformed CSV, an unexpected API answer) | Check the input file; for an API answer, run with --verbose and report it |
| 66 | An input file cannot be opened | Check the path and its permissions |
| 67 | An asset, folder, tenant or environment does not exist | Check the spelling; paths start at / (Physna shows the root as "Home", and /Home/... works too) |
| 68 | The deployment lacks a feature (failure diagnostics) or doctor could not reach a server | See Proxies, Certificates and Timeouts |
| 69 | Try again later: rate limited, a server error that outlasted the retries, a batch with failed items, a report still running | Run again later; for a batch, the summary lists what failed |
| 78 | The configuration is broken | pcli2 config validate, then pcli2 env list |
| 100 | Not logged in, or the credentials were rejected | pcli2 auth login |
| 101 | The network failed | See Proxies, Certificates and Timeouts |
| 102 | The API rejected the request | The message carries the server's reason |
Common situations
"Access token not found": run pcli2 auth login. In CI, set
PCLI2_CLIENT_ID and PCLI2_CLIENT_SECRET first.
"No tenant specified and no active tenant selected": run pcli2 tenant use
(or pass --tenant to the command).
A folder path is "not found" but exists: the folder cache may predate the
folder; add --reload to folder list or asset list, or run
pcli2 cache clear.
An asset shows failed: pcli2 asset diagnose --path <path> asks Physna why;
pcli2 tenant failures lists what failed recently.
Bulk commands are slow or rate limited: folder commands run four items at a
time by default; lower it with --concurrent 1 or space items out with
--delay.
Seeing what pcli2 does: --verbose prints pcli2's own debug log on stderr;
RUST_LOG=debug opens up the HTTP stack as well. --stats prints the number of
API requests, retries and token renewals at the end.
Checking the basics
pcli2 auth expiration # logged in, and for how long
pcli2 tenant get # the active tenant
pcli2 env get # the active environment and its URLs
pcli2 config get path # where the configuration lives
pcli2 config validate --api # configuration, credentials and a test call
Reporting a problem
Include the output of pcli2 --version and pcli2 doctor, the command you
ran, and the message (with --verbose if you can reproduce it). An internal
error (exit 70) is always a bug.