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

Reference

Help

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, and pcli2 doctor for 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 withUpdate with
Shell or PowerShell installerpcli2-update
Homebrewbrew upgrade pcli2 (after the one-time brew trust jchultarsky101/pcli2 on Homebrew 6)
MSIDownload 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:

OldNew
asset create --fileasset create --input
asset create-batch --filesasset create-batch --input
asset metadata create-batch --csv-fileasset metadata create-batch --input
folder upload --local-pathfolder upload --input
config import --fileconfig import --input
asset thumbnail --fileasset 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

  1. Command not found: the install directory is not on your PATH; the installer prints the directory it used.
  2. An old version keeps running: which -a pcli2 (or where pcli2 on Windows) lists every copy on the PATH; remove the stale one.
  3. 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

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:

This is the newer, more user-friendly approach available to administrators:

  1. Log in to your Physna instance
  2. (Optional) Select a tenant from the tenant selector
  3. Click on Settings (the gear icon in the top-right corner)
  4. Navigate to the Users tab
  5. Create a new service account
  6. 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:

  1. Navigate to the Physna OpenAPI Documentation page
  2. Log in with your Physna credentials
  3. Locate and execute the POST /users/me/service-accounts endpoint
  4. 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

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

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

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, and pcli2 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

--recursive can 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. MATERIAL over a REF and a CAN sub-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_PERCENTAGE column 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_URL is 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 xls format always includes metadata (the metadata diff is its whole point), so the --metadata flag 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, --exclusive and (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:

  1. Use a checkpoint: --checkpoint FILE makes an interruption cost minutes instead of hours
  2. Adjust threshold: Higher thresholds reduce processing time
  3. Increase concurrency: Use more concurrent operations (but watch resource usage)
  4. 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-uuid or --reference-path
  • Candidate (target) asset: --candidate-uuid or --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) and totalMm3
  • sourceHoleMisses / targetHoleMisses: The holes found on one side with no counterpart on the other, each with its aligned centre (centerMm), unit axis and radiusMm
  • 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

  1. Use appropriate thresholds: Start with 80-85% and adjust based on results
  2. Limit search scope: Use specific folders rather than searching entire tenants
  3. Monitor resource usage: Adjust concurrency based on your system capabilities
  4. 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

  1. Schedule regular deduplication: Run geometric matching periodically to identify duplicates
  2. Integrate with CI/CD: Use geometric matching in automated workflows
  3. 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:

  1. Reduce concurrency: Lower the --concurrent value
  2. Increase threshold: Use higher threshold values to reduce matches
  3. Check network: Ensure good connectivity to the Physna API
  4. Monitor server status: Check if the Physna service is experiencing issues

Incomplete Results

If you're not seeing expected matches:

  1. Lower threshold: Try lower threshold values
  2. Check asset types: Ensure assets are compatible geometric file types
  3. Verify permissions: Confirm you have access to all assets in the search scope
  4. Contact support: If issues persist, reach out to Physna support
  • asset geometric-match - Find matches for a single asset
  • folder geometric-match - Find matches for all assets in a folder
  • asset similarity - Get pairwise match scores between two specific assets (alias: asset match-scores)
  • asset list - List assets in a folder
  • asset 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

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
CommandAlias--threshold means
catalog geometric-matchgmminimum similarity, 0-100 (default 80)
catalog part-matchpmminimum similarity, 0-100 (default 80)
catalog visual-matchvmsize 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

CodeWhen
0The search ran (with or without matches)
64--in is not one of your catalogs, or you have several and named none
68Catalog search is not enabled for your account
102The 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,VALUE in that order, optionally followed by TYPE
  • 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, and NX/part.prt all 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-empty is passed
  • TYPE (optional): One of text (default), number, boolean, or url. 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 the TYPE column 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, or metadata:* 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:

  1. Export Metadata in the ASSET_PATH,NAME,VALUE layout that create-batch reads. asset metadata get shows one asset's fields as NAME,VALUE (no path, so it cannot be imported back); for a folder, build the file from the JSON listing with jq:

    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
    
  2. 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
  3. 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:

  1. Text (default): String values

    pcli2 asset metadata create --path "/Home/Model.stl" --name "Description" --value "Sample part description" --type "text"
    
  2. Number: Numeric values

    pcli2 asset metadata create --path "/Home/Model.stl" --name "Weight" --value "15.5" --type "number"
    
  3. Boolean: True/False values

    pcli2 asset metadata create --path "/Home/Model.stl" --name "Approved" --value "true" --type "boolean"
    
  4. 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 number field receives 18 (a JSON number) rather than the string "18"; 84.50 is sent as 84.5
  • A boolean field accepts true/false, 1/0, yes/no, on/off (case-insensitive)
  • text and url fields 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 --type flag (single create) and the TYPE column (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

  1. Use Descriptive Names: Choose clear, consistent names for metadata fields across your organization
  2. Validate Data Types: Ensure values match the expected data type for each field
  3. Batch Operations: Use CSV batch operations for large-scale metadata updates
  4. Backup Before Bulk Operations: Export metadata before performing bulk deletions
  5. Test First: Use small test sets before applying operations to large asset collections
  6. 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-error to 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-error to 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

  1. API Rate Limits: Extensive operations may be rate-limited by the Physna API
  2. Processing Time: Large batch operations can take considerable time
  3. Metadata Types: Supports text, number, boolean, and url metadata fields
  4. Asset Access: Can only process assets accessible to your authenticated user
  5. 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:

  1. Taking a reference asset and specified metadata fields
  2. Finding geometrically similar assets using the Physna geometric search
  3. 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

  1. API Rate Limits: Large operations may be rate-limited by the Physna API
  2. Processing Time: Large operations can take considerable time
  3. Metadata Types: Supports text, number, boolean and url metadata fields
  4. 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

# 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:

FlagMeaning
--folder-path PA folder to search, subfolders included (repeatable). / means the root's own assets (see --include-home).
--exclude-folder-path PA subfolder of a searched folder to leave out, with its own subfolders (repeatable).
--extension EOnly assets with this file extension, e.g. stl (repeatable).
--min-threshold N / --max-threshold NSimilarity range, 0 to 100 (default 80 to 100).
--exclude-assembliesLeave assemblies out of the groups.
--exclude-exact-duplicatesLeave out 100% matches that share a file name.
--include-homeInclude the root folder's own assets.
--waitPoll until the report is COMPLETED, FAILED or CANCELLED, printing progress on stderr.
--poll-interval SSeconds 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

CodeWhen
0Done; for diagnose, found and not-found alike
64Download of a FAILED or CANCELLED report; bad thresholds; a refused confirmation prompt
67The report id does not exist
68diagnose on a deployment without failure log search
69Download 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

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
FieldMeaning
levelERROR, WARN, INFO or DEBUG, matching the log lines
codeThe process exit code, on the final error object
kindThe failure class: usage, data, no_input, not_found, unavailable, temp_fail, software, os, config, auth, network, api
messageThe same text the human-readable error would show
hintWhat to do about it, when pcli2 knows
http_statusThe HTTP status behind an API error, when there is one
stepsRemediation 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:

CodeMeaning
0Success
64Command line usage error
65Data format error
66Cannot open input file
67Resource not found
68Service unavailable
69Temporary failure
70Internal software error
71Operating system error
78Configuration error
100Authentication error
101Network communication error
102Remote 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 CommandAlias
pcli2 tenant listpcli2 tenant ls
pcli2 tenant usepcli2 tenant select
pcli2 tenant getpcli2 tenant current
pcli2 tenant clearpcli2 tenant unset
pcli2 tenant metadata listpcli2 tenant metadata ls

Folder Commands

Full CommandAlias
pcli2 folder listpcli2 folder ls
pcli2 folder deletepcli2 folder rm
pcli2 folder getpcli2 folder cat
pcli2 folder createpcli2 folder add
pcli2 folder movepcli2 folder mv
pcli2 folder renamepcli2 folder ren
pcli2 folder resolvepcli2 folder res
pcli2 folder description clearpcli2 folder description rm
pcli2 folder downloadpcli2 folder dl
pcli2 folder geometric-matchpcli2 folder geometric-search, pcli2 folder gm
pcli2 folder part-matchpcli2 folder part-search, pcli2 folder pm
pcli2 folder visual-matchpcli2 folder visual-search, pcli2 folder vm

Asset Commands

Full CommandAlias
pcli2 asset listpcli2 asset ls
pcli2 asset deletepcli2 asset rm
pcli2 asset getpcli2 asset cat
pcli2 asset createpcli2 asset upload
pcli2 asset create-batchpcli2 asset upload-batch
pcli2 asset downloadpcli2 asset dl
pcli2 asset dependenciespcli2 asset deps
pcli2 asset dependency-diffpcli2 asset deps-diff
pcli2 asset thumbnailpcli2 asset thumb
pcli2 asset geometric-matchpcli2 asset geometric-search, pcli2 asset gm
pcli2 asset part-matchpcli2 asset part-search, pcli2 asset pm
pcli2 asset visual-matchpcli2 asset visual-search, pcli2 asset vm
pcli2 asset text-matchpcli2 asset text-search, pcli2 asset tm
pcli2 asset similaritypcli2 asset match-scores
pcli2 asset diagnosepcli2 asset failure, pcli2 asset why
pcli2 asset movepcli2 asset mv
pcli2 asset resolve-dependencypcli2 asset resolve-dep
pcli2 asset metadata createpcli2 asset metadata update
pcli2 asset metadata create-batchpcli2 asset metadata update-batch
pcli2 asset metadata deletepcli2 asset metadata rm

Authentication Commands

Full CommandAlias
pcli2 authpcli2 a
pcli2 auth loginpcli2 auth in
pcli2 auth logoutpcli2 auth out
pcli2 auth getpcli2 auth token
pcli2 auth clear-tokenpcli2 auth clear
pcli2 auth expirationpcli2 auth exp

Environment Commands

Full CommandAlias
pcli2 environmentpcli2 env
pcli2 environment listpcli2 env ls
pcli2 environment removepcli2 env rm

Catalog Commands

Full CommandAlias
pcli2 catalog listpcli2 catalog ls
pcli2 catalog geometric-matchpcli2 catalog gm
pcli2 catalog part-matchpcli2 catalog pm
pcli2 catalog visual-matchpcli2 catalog vm

Report Commands

Full CommandAlias
pcli2 report listpcli2 report ls
pcli2 report downloadpcli2 report dl
pcli2 report diagnosepcli2 report why
pcli2 report deletepcli2 report rm

Other Commands

Full CommandAlias
pcli2 user listpcli2 user ls
pcli2 cache clearpcli2 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 inventory outputs the full list of assets (same format as asset list)
  • asset counts outputs 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-uuid or --reference-path
  • --candidate-uuid or --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 by TYPE
  • 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_PATH but different NAME and VALUE combinations
  • TYPE is optional (default text; one of text, number, boolean, url) and only sets the type used when registering a new field — for an existing field, its registered type is authoritative and TYPE is ignored
  • A leading /Home in ASSET_PATH (Physna's name for the root folder) is treated as the root, so /Home/NX/part.prt and NX/part.prt refer 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
  • path is the asset path; the optional id column 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-path or --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 --reload flag 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: user means the failure is yours to fix and summary says what (an unsupported format, for example). kind: internal means it failed on Physna's side: quote the traceId to 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 doctor has a diagnostics line 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"
VariableEffect
PCLI2_CONFIG_DIRDirectory holding config.yml and dev_credentials.json. Default: the platform configuration directory (pcli2 config get path prints it).
PCLI2_CACHE_DIRDirectory for all cache files. Default: the platform cache directory.
PCLI2_FORMATDefault --format when the flag is not given on the command line.
PCLI2_HEADERSDefault --headers when the flag is not given (1/0, yes/no).
PCLI2_LOG_LEVELLog level: error, warn (default), info, debug, trace. RUST_LOG takes precedence when set.
PCLI2_TIMEOUTTotal 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_RETRIESRetries 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_COLORDisable 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_CSVGuard CSV output against spreadsheet formula injection. Same as --safe-csv.
PCLI2_NO_INPUTNever prompt; a command that would need an answer exits 64 instead. Same as --no-input.
PCLI2_ERROR_FORMATtext (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, CIDisable the once-a-day new-version hint.
PCLI2_TENANTTenant for this command only, like --tenant. pcli2 tenant use changes the saved default.
PCLI2_ENVEnvironment for this command only, like --env. Nothing is saved, so scripts can target different environments at the same time.
PCLI2_CLIENT_ID, PCLI2_CLIENT_SECRETCredentials 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.com and 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.com for the latest release to tell you about updates. Set PCLI2_NO_UPDATE_CHECK=1 to 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.com for the once-a-day update hint (PCLI2_NO_UPDATE_CHECK=1 turns it off).

pcli2 env get shows the URLs of the active environment.

Timeouts and retries

SettingDefaultChange with
Connecting15 seconds-
No data received on an open connection5 minutes-
Whole request (large uploads and downloads)30 minutesPCLI2_TIMEOUT (seconds)
Retries of transient failures2PCLI2_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).

CodeMeaningWhat to do
64The command line is wrong, or a prompt was needed with --no-inputRead the message; --help on the command shows its flags and examples
65Data 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
66An input file cannot be openedCheck the path and its permissions
67An asset, folder, tenant or environment does not existCheck the spelling; paths start at / (Physna shows the root as "Home", and /Home/... works too)
68The deployment lacks a feature (failure diagnostics) or doctor could not reach a serverSee Proxies, Certificates and Timeouts
69Try again later: rate limited, a server error that outlasted the retries, a batch with failed items, a report still runningRun again later; for a batch, the summary lists what failed
78The configuration is brokenpcli2 config validate, then pcli2 env list
100Not logged in, or the credentials were rejectedpcli2 auth login
101The network failedSee Proxies, Certificates and Timeouts
102The API rejected the requestThe 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.