PCLI2 Documentation

Welcome to the PCLI2 documentation! This guide will help you get started with the Physna Command Line Interface v2.

Table of Contents

• Installation Guide - How to install and set up PCLI2
• Quick Start Guide - Getting started with basic commands
• Geometric Matching - Comprehensive guide to finding similar assets
• Cross-Platform Configuration - Environment variables for cross-platform support
• Documentation Deployment - Setting up documentation website with Oranda and GitHub Pages

Introduction

PCLI2 is a powerful command-line interface for the Physna public API that enables advanced 3D geometry search and analysis. It provides intuitive nested sub-commands, sensible defaults, and configuration management for seamless integration with Physna's advanced features.

Features

• Intuitive command structure with nested sub-commands
• Configuration management for persistent settings
• Asset operations (create, list, get, delete, update)
• Folder operations (create, list, get, delete, update)
• Tenant management with multi-tenant support
• Authentication with OAuth2 client credentials flow
• Batch operations for processing multiple assets
• Geometric matching for finding similar assets
• Export/Import functionality for data migration
• Context management for working with multiple tenants
• Cross-platform support with environment variable configuration

Getting Started

To get started with PCLI2, follow the Installation Guide to set up the tool on your system, then check out the Quick Start Guide to begin using basic commands.

Installation Guide

This guide explains how to install and set up PCLI2 on your system.

Table of Contents

• Prerequisites
• Installation Methods
• Verifying Installation
• Updating PCLI2
• Troubleshooting

Prerequisites

Before installing PCLI2, ensure you have the following:

• Rust toolchain (latest stable version)
• Cargo package manager (usually installed with Rust)
• Git (for cloning the repository)

Installing Rust

If you don't have Rust installed, you can install it using rustup:

# Install Rust using rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Reload your shell or source the rustup environment
source ~/.cargo/env

# Verify the installation
rustc --version
cargo --version

Installation Methods

Method 1: Pre-built Binaries (Recommended)

PCLI2 provides pre-built binaries for Windows, macOS, and Linux through GitHub Releases:

1. Visit the Latest Release
2. Download the appropriate installer or binary for your platform:
   • Windows: pcli2-x86_64-pc-windows-msvc.msi (Installer) or pcli2-x86_64-pc-windows-msvc.zip (ZIP)
   • macOS: pcli2-installer.sh (Universal script) or platform-specific archives
   • Linux: pcli2-installer.sh (Universal script) or pcli2-x86_64-unknown-linux-gnu.tar.xz (Archive)

Using the Universal Installer Script:

# Download and run the installer script
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/physna/pcli2/releases/latest/download/pcli2-installer.sh | sh

Manual Installation:

# Extract the archive (example for Linux)
tar -xf pcli2-x86_64-unknown-linux-gnu.tar.xz
sudo cp pcli2 /usr/local/bin/

Method 2: Building from Source

This method gives you the latest development version of PCLI2:

# Clone the repository
git clone https://github.com/physna/pcli2.git
cd pcli2

# Build the project (this may take a few minutes)
cargo build --release

# The executable will be located at target/release/pcli2
# You can copy it to a directory in your PATH
sudo cp target/release/pcli2 /usr/local/bin/

# Or add the target directory to your PATH in ~/.bashrc or ~/.zshrc
echo 'export PATH="$PATH:/path/to/pcli2/target/release"' >> ~/.bashrc

Method 3: Installing via Cargo

If you want to install PCLI2 directly from crates.io (once published):

# Install PCLI2 globally
cargo install pcli2

# Verify the installation
pcli2 --version

Verifying the Installation

After installation, verify that PCLI2 is working correctly:

# Check the version
pcli2 --version

# View available commands
pcli2 --help

# View asset-related commands
pcli2 asset --help

Updating PCLI2

To update PCLI2 when building from source:

# Navigate to your PCLI2 directory
cd /path/to/pcli2

# Pull the latest changes
git pull

# Rebuild the project
cargo build --release

# Copy the updated binary (if needed)
sudo cp target/release/pcli2 /usr/local/bin/

Troubleshooting

Common Issues

1. Permission denied when copying binary: Use sudo or copy to a directory you own
2. Command not found: Ensure the binary directory is in your PATH
3. Build failures: Make sure you have the latest stable Rust version

Getting Help

If you encounter issues during installation:

1. Check that all prerequisites are met
2. Verify your Rust installation is working
3. Consult the GitHub Issues page
4. Contact the Physna development team for support

Quick Start Guide

This guide will help you get started with PCLI2 quickly by walking through common tasks.

Table of Contents

• Installation
• Authentication
• Basic Navigation
• Working with Assets
• Geometric Matching
• Configuration
• Context Management
• Next Steps
• Getting Help

Authentication

Before using most PCLI2 commands, you need to authenticate with your Physna tenant. First, you'll need to obtain your API credentials.

Getting API Credentials

There are two methods to obtain your API credentials:

Method 1: Using the Physna Web Interface (Recommended)

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

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 with client credentials
pcli2 auth login --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

# Verify authentication
pcli2 auth get

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 --path /Root/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 --file path/to/my/model.stl --path /Root/MyFolder/

For bulk operations, asset create-batch allows you to upload multiple files at once using glob patterns:

# Upload multiple assets
pcli2 asset create-batch --files "models/*.stl" --path /Root/BatchUpload/

Viewing and Managing Assets

Use these commands to inspect and manage your assets:

# View asset details
pcli2 asset get --path /Root/MyFolder/model.stl

# Delete an asset
pcli2 asset delete --path /Root/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 /Root/Folder/ReferenceModel.stl --threshold 85.0

# Find matches for all assets in a folder (parallel processing)
pcli2 asset geometric-match-folder --path /Root/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 "/Root/Folder/Model.stl" --name "Material" --value "Steel" --type "text"

# Add or update multiple metadata fields on an asset
pcli2 asset metadata create --path "/Root/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 "/Root/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 "/Root/Folder/Model.stl" --name "Material" --name "Weight"

# Delete metadata fields using comma-separated list
pcli2 asset metadata delete --path "/Root/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 /Root/Folder/ReferenceModel.stl --name "Material,Cost" --threshold 85.0

# Apply metadata recursively to create chains of similar assets
pcli2 asset metadata inference --path /Root/Folder/ReferenceModel.stl --name "Category" --threshold 90.0 --recursive

# Apply multiple metadata fields with different thresholds
pcli2 asset metadata inference --path /Root/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:

# View current configuration
pcli2 config get

# Export configuration for backup
pcli2 config export --output my-config.yaml

# Import configuration from a file
pcli2 config import --file 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 config environment 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 config environment 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 config environment list

# Switch to an environment (with interactive selection)
pcli2 config environment use

# Or switch to an environment by name
pcli2 config environment use --name development

# Get details of the active environment
pcli2 config environment get

# Get details of a specific environment
pcli2 config environment get --name production

# Reset all environment configurations
pcli2 config environment 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)

Context Management

Work with multiple tenants efficiently:

# Set active context (tenant) using either tenant name or ID
pcli2 context set --tenant "Demo Environment 1"

# Or using tenant ID
pcli2 context set --tenant 123e4567-e89b-12d3-a456-426614174000

# View current context
pcli2 context get

# Clear active context
pcli2 context clear

Next Steps

After completing this quick start guide, explore these topics:

1. Command Reference - Detailed information about all available commands
2. Batch Operations - Learn to process multiple assets efficiently
3. Geometric Matching - Advanced techniques for finding similar assets
4. Configuration - Customize PCLI2 to your workflow

Getting Help

For help with any command, use the built-in help system:

# General help
pcli2 --help

# Help for a specific command group
pcli2 asset --help

# Help for a specific command
pcli2 asset create --help

You can also use the -h or --help flag with any command to get detailed usage information.

Geometric Matching

PCLI2 provides powerful geometric matching capabilities to find similar assets in your Physna tenant. This feature leverages advanced algorithms to identify assets with similar geometries, regardless of their orientation, scale, or position.

Table of Contents

• Overview
• Single Asset Matching
• Folder-Based Matching
• Threshold Settings
• Performance Options
• Error Handling
• Best Practices
• Advanced Usage
• Troubleshooting

Overview

Geometric matching helps you:

• Find duplicate or near-duplicate assets
• Identify variations of the same part
• Locate similar components across different projects
• Reduce storage costs by identifying redundant assets
• Improve design workflows by finding existing similar parts

Related Features

Geometric matching serves as the foundation for other powerful capabilities:

• Metadata Inference: Automatically propagate metadata from reference assets to geometrically similar assets using pcli2 asset metadata inference
• Metadata Management: Create, update, retrieve, and delete metadata for assets using commands like pcli2 asset metadata create, pcli2 asset metadata get, 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 /Root/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 /Root/Folder/ReferenceModel.stl --threshold 80.0 --format csv --headers

# Find matches with CSV output, headers, and metadata
pcli2 asset geometric-match --path /Root/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": "/Root/Folder/ReferenceModel.stl",
    "candidateAssetPath": "/Root/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,/Root/Folder/ReferenceModel.stl,/Root/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 CAND_ 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,CAND_MATERIAL,REF_COLOR,CAND_COLOR
/Root/Folder/ReferenceModel.stl,/Root/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 /Root/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
/Root/Folder/ReferenceModel.stl,/Root/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 /Root/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,CAND_MATERIAL,REF_COLOR,CAND_COLOR
/Root/Folder/ReferenceModel.stl,/Root/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 asset geometric-match-folder --folder-path /Root/SearchFolder/ --threshold 85.0

Comparison Viewer URL

Both geometric-match and geometric-match-folder 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}

Performance Options

Concurrency Control

Control how many simultaneous operations are performed (range: 1-10, default: 1):

# Use 8 concurrent operations (default is 1, maximum is 10)
pcli2 asset geometric-match-folder --folder-path /Root/SearchFolder/ --concurrent 8

# Use the default (1 concurrent operation)
pcli2 asset geometric-match-folder --folder-path /Root/SearchFolder/

# Invalid values will cause the command to fail
pcli2 asset geometric-match-folder --folder-path /Root/SearchFolder/ --concurrent 15
# This will show an error: "Invalid value for '--concurrent': must be between 1 and 10, got 15"

Progress Tracking

Display progress information during long-running operations:

# Show progress information
pcli2 asset geometric-match-folder --folder-path /Root/SearchFolder/ --progress

# Combine with concurrency to show multiple progress bars (one per concurrent operation)
pcli2 asset geometric-match-folder --folder-path /Root/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)

Performance Options

Concurrency and Progress Combined

For optimal performance monitoring, combine both options:

# Use 10 concurrent operations with detailed progress tracking
pcli2 asset geometric-match-folder --folder-path /Root/SearchFolder/ --concurrent 10 --progress

# Combine with other options
pcli2 asset geometric-match-folder --folder-path /Root/SearchFolder/ --threshold 85.0 --concurrent 8 --progress

Handling Large Folders

For folders with many assets, consider these strategies:

1. Adjust threshold: Higher thresholds reduce processing time
2. Increase concurrency: Use more concurrent operations (but watch resource usage)
3. Process in batches: Break large folders into smaller subfolders

Error Handling

Common Errors

HTTP 409 Conflict

When the server is busy or rate-limiting requests:

ERROR: Error performing geometric search for asset XXX after 3 retries: HTTP error: HTTP status client error (409 Conflict)

PCLI2 automatically retries up to 3 times with 500ms delays between attempts.

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=("/Root/ProjectA/" "/Root/ProjectB/" "/Root/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 asset geometric-match-folder \
        --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 = @("/Root/ProjectA/", "/Root/ProjectB/", "/Root/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 asset geometric-match-folder `
        --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

Related Commands

• asset geometric-match - Find matches for a single asset
• asset geometric-match-folder - Find matches for all assets in a folder
• asset list - List assets in a folder
• asset get - Get detailed asset information

Use pcli2 asset geometric-match --help and pcli2 asset geometric-match-folder --help for detailed command information.

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 "/Root/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 "/Root/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 "/Root/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"

The delete command now uses the dedicated API endpoint to properly remove metadata fields from assets, rather than fetching all metadata and re-updating the asset without the specified fields. This provides more efficient and accurate metadata deletion.

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 --csv-file "metadata.csv"

CSV Format for Batch Metadata Operations

The CSV format used by asset metadata get --format csv and asset metadata create-batch --csv-file is designed for seamless round-trip operations:

ASSET_PATH,NAME,VALUE
/Root/Folder/Model1.stl,Material,Steel
/Root/Folder/Model1.stl,Weight,"15.5 kg"
/Root/Folder/Model2.ipt,Material,Aluminum
/Root/Folder/Model2.ipt,Supplier,Richardson Electronics

The CSV format specifications:

• Header Row: Must contain exactly ASSET_PATH,NAME,VALUE in that order
• ASSET_PATH: Full path to the asset in Physna (e.g., /Root/Folder/Model.stl)
• NAME: Name of the metadata field to set
• VALUE: Value to assign to the metadata field
• 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 --csv-file "metadata.csv"

Note: The create-batch command processes each row as a single metadata field assignment for an asset. Multiple rows with the same ASSET_PATH will update multiple metadata fields for that asset in a single API call.

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:

   # Export all metadata for an asset to a CSV file
   pcli2 asset metadata get --path "/Root/Folder/Model.stl" --format csv > model_metadata.csv
   
   # Export metadata for multiple assets in a folder
   pcli2 asset list --path "/Root/Folder/" --metadata --format 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
   • Save the file in CSV format

3. Reimport Modified Metadata:

   # Update assets with modified metadata
   pcli2 asset metadata create-batch --csv-file "modified_metadata.csv"
   

This workflow enables powerful bulk metadata operations while maintaining the flexibility to use familiar spreadsheet tools for data manipulation.

Metadata Field Types

PCLI2 supports three metadata field types:

1. Text (default): String values

   pcli2 asset metadata create --path "/Root/Model.stl" --name "Description" --value "Sample part description" --type "text"
   

2. Number: Numeric values

   pcli2 asset metadata create --path "/Root/Model.stl" --name "Weight" --value "15.5" --type "number"
   

3. Boolean: True/False values

   pcli2 asset metadata create --path "/Root/Model.stl" --name "Approved" --value "true" --type "boolean"
   

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

The metadata operations are designed to be resilient:

• Continues processing even if individual asset operations fail
• Provides detailed error messages for troubleshooting
• Automatically handles network failures with retries
• Validates input formats before processing

Common error scenarios and their handling:

• Missing assets: Command skips missing assets with appropriate warnings
• Network failures: Individual operations retry, overall process continues
• Permission issues: Skips inaccessible assets with warning messages
• Invalid metadata: Logs error but continues processing other assets
• API rate limits: Respects rate limits and waits before retrying

Performance Considerations

Large-Scale Operations

For bulk metadata operations:

# Process during off-peak hours
pcli2 asset metadata create-batch --csv-file "large_metadata.csv"

Monitoring Progress

Monitor progress during long-running operations:

# Show progress during batch operations
pcli2 asset metadata create-batch --csv-file "metadata.csv" --progress

Integration with Other Commands

Metadata operations work seamlessly with other PCLI2 commands:

# Chain with asset operations
pcli2 asset list --path "/Root/Parts/" --format csv | \
pcli2 asset metadata create-batch --csv-file "metadata_updates.csv"

# Export results for auditing
pcli2 asset metadata get --path "/Root/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: Only supports text, number, and boolean 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
4. Optionally continuing the process recursively for discovered matches

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 /Root/Parts/Bolt-M8x20.stl --name "Material" --threshold 90.0

This command will:

• Find the asset at /Root/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 /Root/Parts/BaseModel.stl --name "Material,Cost,Supplier" --threshold 85.0

# Using multiple --name flags
pcli2 asset metadata inference --path /Root/Parts/BaseModel.stl --name "Material" --name "Cost" --name "Supplier" --threshold 85.0

Recursive Processing

Enable recursive processing to apply metadata inference to discovered matches:

pcli2 asset metadata inference --path /Root/Parts/Reference.stl --name "Category" --threshold 80.0 --recursive

With the --recursive flag, the system will:

1. Process the initial reference asset
2. Find and process similar assets (first level)
3. Continue finding and processing matches of those matches (second level)
4. And so on, until no new assets are discovered

The system automatically prevents infinite loops by tracking processed assets.

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 /Root/Parts/Reference.stl --name "CriticalField" --threshold 95.0

# Liberal matching (find more potential matches)
pcli2 asset metadata inference --path /Root/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 /Root/StandardParts/Bolt-M8x20.stl --name "Material" --threshold 92.0 --recursive

Categorizing Product Lines

# Assign category and supplier information to a product family
pcli2 asset metadata inference --path /Root/ProductLine/MainAssembly.stl --name "Category,Supplier,Division" --threshold 85.0

Cost Propagation

# Apply estimated costs to similar components
pcli2 asset metadata inference --path /Root/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 /Root/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 /Root/Test/Reference.stl --name "TestTag" --threshold 85.0

3. Use Recursive Carefully

Recursive processing can be powerful but may affect many assets. Always review the scope first:

# First, see what would be affected without actually applying changes
pcli2 asset geometric-match --path /Root/Parts/Reference.stl --threshold 80.0 --format csv > potential_matches.csv

# Then proceed with metadata inference if results look good
pcli2 asset metadata inference --path /Root/Parts/Reference.stl --name "Category" --threshold 80.0 --recursive

4. Combine with Geometric Matching

Use geometric matching first to preview results, then apply metadata inference:

# Preview matches
pcli2 asset geometric-match --path /Root/Parts/Reference.stl --threshold 85.0 --format csv

# Apply metadata if preview looks good
pcli2 asset metadata inference --path /Root/Parts/Reference.stl --name "Material" --threshold 85.0

Error Handling

The metadata inference command is designed to be resilient:

• Continues processing even if individual asset operations fail
• Provides detailed error messages for troubleshooting
• Automatically skips inaccessible assets
• Prevents infinite loops in recursive mode

Common error scenarios and their handling:

• Missing reference asset: Command aborts with clear error message
• Network failures: Individual operations retry, overall process continues
• Permission issues: Skips problematic assets with warning messages
• Invalid metadata: Logs error but continues processing other assets

Performance Considerations

Large-Scale Operations

For bulk metadata inference operations:

# Process during off-peak hours
pcli2 asset metadata inference --path /Root/LargeAssembly/Reference.stl --name "Category" --threshold 80.0 --recursive

Monitoring Progress

Monitor progress during long-running operations using the available flags:

pcli2 asset metadata inference --path /Root/Parts/Reference.stl --name "Material" --threshold 85.0 --recursive

Integration with Other Commands

Metadata inference works seamlessly with other PCLI2 commands:

# Chain with folder operations
pcli2 folder list --path /Root/ProductLine/ | \
pcli2 asset metadata inference --name "ProductLine" --threshold 85.0 --recursive

# Export results for auditing
pcli2 asset metadata inference --path /Root/Parts/Reference.stl --name "Category" --threshold 85.0 --recursive \
  --format csv > metadata_propagation_log.csv

Limitations

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

Cross-Platform Configuration

PCLI2 supports cross-platform environments through environment variables, which is especially useful for WSL users running Windows executables or users who want to customize where configuration and cache files are stored.

Environment Variables

# Set custom configuration directory (cross-platform support)
export PCLI2_CONFIG_DIR="/custom/path/to/config"

# Set custom cache directory (for all cache files)
export PCLI2_CACHE_DIR="/custom/path/to/cache"

# Set custom API, UI, and Auth URLs (overrides configuration)
export PCLI2_API_BASE_URL="https://custom-api.example.com/v3"
export PCLI2_UI_BASE_URL="https://custom-ui.example.com"
export PCLI2_AUTH_BASE_URL="https://custom-auth.example.com/oauth2/token"

# Useful for WSL users running Windows executables
export PCLI2_CONFIG_DIR="/home/$USER/.pcli2"
export PCLI2_CACHE_DIR="/home/$USER/.pcli2/cache"

Environment Variable Details:

• PCLI2_CONFIG_DIR: Custom directory for configuration file (config.yml). If not set, uses the system's default configuration directory.
• PCLI2_CACHE_DIR: Custom directory for all cache files (asset cache, metadata cache, folder cache). If not set, uses the system's default cache directory.
• PCLI2_API_BASE_URL: Custom API base URL (overrides configuration). If not set, uses the configured or default API URL.
• PCLI2_UI_BASE_URL: Custom UI base URL (overrides configuration). If not set, uses the configured or default UI URL.
• PCLI2_AUTH_BASE_URL: Custom authentication URL (overrides configuration). If not set, uses the configured or default auth URL.

These environment variables allow PCLI2 to work seamlessly across different operating systems and environments, including:

• Windows (native)
• macOS (native)
• Linux (native)
• Windows Subsystem for Linux (WSL)
• Docker containers
• CI/CD environments

Documentation Deployment Instructions

GitHub Pages Setup

To deploy the Oranda-generated documentation to GitHub Pages, follow these steps:

1. Enable GitHub Pages:

   • Go to your repository settings: https://github.com/jchultarsky101/pcli2/settings
   • Scroll down to the "Pages" section
   • Under "Source", select "GitHub Actions" as the source
   • Click "Save"

2. Trigger the Documentation Deployment:

   • Push a commit to the main branch to trigger the documentation workflow
   • Or manually trigger the workflow from the GitHub Actions page

3. Access Your Documentation:

   • Once the workflow completes successfully, your documentation will be available at: https://jchultarsky101.github.io/pcli2

Local Development

To preview the documentation locally:

# Install Oranda if you haven't already
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/oranda/releases/latest/download/oranda-installer.sh | sh

# Build the documentation
oranda build

# Serve locally (if you have a simple HTTP server)
cd public
python3 -m http.server 8000
# Then visit http://localhost:8000

Workflow Details

The documentation workflow (documentation.yml) will:

• Automatically build documentation on pushes to the main branch
• Deploy the documentation to GitHub Pages
• Run on manual triggers via workflow_dispatch

Troubleshooting

If the documentation doesn't appear:

1. Check that GitHub Pages is set to use "GitHub Actions" as the source
2. Verify the documentation workflow ran successfully
3. Check the workflow logs for any errors