Quick Start Guide

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

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 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 --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 (deletes the old one first)
pcli2 asset create --input path/to/my/model.stl --folder-path /Home/MyFolder/ --override

# Replace an existing asset and keep its metadata
pcli2 asset create --input path/to/my/model.stl --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

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"

# Add or update multiple metadata fields on an asset
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

# Apply metadata recursively to create chains of similar assets

# Apply multiple metadata fields with different thresholds
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)

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

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.