runscript
runscript loads and runs a .pdmshell script file. Connect to the vault before running it, even when the script file is stored outside the vault.
Use it when you want to keep shared automation in one script and call it from another command, from the visual editor, or directly from pdmcli.exe.
Syntax
runscript -source "C:\Vault\Scripts\CreateECO.pdmshell"
runscript -source "C:\Vault\Scripts\CreateECO.pdmshell" -filePath "C:\Vault\Parts\1001.sldprt"
runscript -source "C:\Vault\Scripts\CreateECO.pdmshell" -search "Name=%.sldprt" -recursive
runscript -source "C:\Vault\Scripts\CreateECO.pdmshell" -items "123,45;678,90"
Use -id instead of -filePath to select the affected PDM file. It does not select the script: -source always identifies the script to run. See File IDs and paths.
Parameters
| Parameter | Alias | Required | Description |
|---|---|---|---|
-source (default) |
Yes | PDMShell script file path | |
-filePath |
No | File path of the affected document to run the PDMShell script on. | |
-search |
No | Search query used to find matching files in the current directory. | |
-recursive |
No | When used with search, includes matching files in subfolders. | |
-items |
No | Semicolon-separated complete PDM file/folder paths or ID pairs (fileId,folderId or folderId,parentFolderId). Paths and pairs can be mixed. |
|
-id |
No | Positive PDM ID of the affected file, instead of -filePath. Use an exact path for a shared file with multiple locations. |
|
-csv |
No | With -search only: write a CSV report of the executed script steps and their outcomes. |
More about parameters
Choose one target selector: -filePath / -id, -search, or -items. Without a target selector, the script runs once in the current session context. Selecting a target supplies placeholder values; commands inside the script still need their own file arguments, such as -filePath "$localPath".
The source script must be readable on this computer. A script already cached in the vault can be referenced relative to the current vault folder. Use a complete path for a script outside the vault; this command does not automatically download an uncached source script.
Items format
Use -items when you already know the complete paths or PDM IDs to process.
runscript -source "C:\Vault\Scripts\CreateECO.pdmshell" -items "123,45;678,90"
You can supply file paths, folder paths, or mix paths with ID pairs:
runscript -source "C:\Vault\Scripts\CreateECO.pdmshell" -items "C:\Vault\Parts\Part1.sldprt;C:\Vault\Projects\ProjectA"
runscript -source "C:\Vault\Scripts\CreateECO.pdmshell" -items "123,45;C:\Vault\Projects\ProjectA"
Separate entries with semicolons and quote the entire list. Paths must be complete drive or UNC paths and resolve in the connected vault; relative paths are not accepted. Spaces and commas within a path are supported. A semicolon always separates entries, so use an ID pair for a path containing a semicolon.
Each folder is one target; its children are not automatically included. Use -search with -recursive when you need matching files below a folder. For a mixed file/folder list, make sure your script's commands support the supplied target types. $localPath supplies the file or folder path; $filePath applies only to files.
Entries are resolved in list order. Invalid or unresolved entries are skipped with a message, and valid entries still run. If none resolve, no script commands run. Resolving targets does not download, check out or check in files.
Use real IDs from the connected vault. File IDs and folder IDs can overlap: the resolver first tries the file and containing-folder pair, then tries a folder with the first ID. -items has no explicit item-type field.
| Item type | Format | Meaning |
|---|---|---|
| File | fileId,folderId |
The first value is the file ID. The second value is the containing folder ID. |
| Folder | folderId,parentFolderId |
The first value is the folder ID. The second value is the parent folder ID. |
Command-line shortcuts
pdmcli.exe can detect a .pdmshell path and convert it to runscript.
pdmcli.exe "C:\Vault\Scripts\CreateECO.pdmshell"
pdmcli.exe "C:\Vault\Scripts\CreateECO.pdmshell" -items "123,45;678,90"
pdmcli.exe "C:\Vault\Scripts\CreateECO.pdmshell" -items "C:\Vault\Parts\Part1.sldprt;C:\Vault\Projects\ProjectA"
Use -edit to open a script in the visual editor without executing it.
pdmcli.exe -edit "C:\Vault\Scripts\CreateECO.pdmshell"
pdmcli.exe "C:\Vault\Scripts\CreateECO.pdmshell" -edit
When runscript loads a script, it appears in the visual editor only when the editor is empty or has no unsaved changes. If the user has unsaved script changes, runscript still executes normally but does not replace the editor contents.
Headless example
Launch a saved script with a list of file paths:
pdmcli.exe -headless "C:\Vault\Scripts\Inspect.pdmshell" -items "C:\Vault\Parts\Part1.sldprt;C:\Vault\Parts\Part2.sldprt"
For this example, Inspect.pdmshell contains:
fileinfo -filePath "$localPath"
quit -silent
Connect through automatic vault login for the account running the process. Keep -headless outside the quoted paths: it is an executable startup option, not a runscript parameter. It opens a smaller shell window; it does not suppress login or command dialogs. quit -silent closes PDMShell when execution reaches that line. See standalone exit codes to wait for completion and check the result.
Placeholder evaluation
When runscript is executed with items, filePath, or search, placeholders are evaluated with the same context used by visual Run command execution.
With optimized script execution, lines without item-specific values run once. Consecutive item-specific lines form a block that runs for each target before the next block begins. Blank lines and comments do not split a block.
File/folder paths and names, IDs, revision/workflow values, PDM variable expressions and event placeholders make a line item-specific. Vault names, user names, dates and times alone do not. Keep -filePath "$localPath" on commands that should act on each file.
Enable Do not use optimized script execution in Settings to run the entire script for the first target, then the entire script for the next. Event-dependent If flows also run per item so each item keeps its own event context.
For until, runscript preserves the -conditions value until the until command runs. This is important when the condition reads a PDM variable that may change while the script is waiting. Other target values, such as -filePath "$localPath", are still resolved for each target item.
Supported placeholders
| Placeholder | Description |
|---|---|
$localPath |
Current file path, or current folder path for a folder target. |
$filePath |
Current file path; empty for a folder-only target. |
$fileName, $filename |
Current file name, including its extension; empty for a folder-only target. |
$name |
Current file or folder name. |
$fileNameWithoutExtension, $nameWithoutExtension |
Current file name without its extension. |
$extension |
File extension including the dot, for example .sldprt. |
$id |
Current file or folder ID. |
$version |
Current PDM file version. Use alongside an item-specific value such as $localPath when processing several files. |
$revision |
Current PDM revision label. |
$state, $stateID |
Current file workflow state name and ID. |
$workflow, $workflowID |
Current file workflow name and ID. |
$folderPath, $directory |
Current folder path. |
$folderName |
Current folder name. |
$folderID |
Current folder ID. |
$vaultName |
Current vault name. |
$vaultRootFolder |
Local vault root folder. |
$GUID |
Identifier shared by the targets in this script invocation. |
$taskName |
Task name when the script host supplies it. A script loaded by runscript does not automatically receive the caller's task name. |
$tempFolder, $TempFolder |
Temporary folder path. |
$machineName, $computerName |
Windows machine name. |
$userName, $username |
Current PDM user name. |
$username.firstName, $username.lastName |
Current PDM user's first and last name when available. |
$username.FullName |
Current PDM user's full name when available. |
$username.email |
Current PDM user's email address when available. |
$windowsUser |
Current Windows user name. |
$userDomain, $domain |
Current Windows domain. |
$yyyy, $year, $yy |
Four-digit or two-digit local year. |
$MM, $mm, $M |
Local month, padded or unpadded. $mm is a month, not minutes. |
$dd, $d |
Local day of the month, padded or unpadded. |
$month, $mon, $day, $dayShort |
Date name values. |
$HH, $hh |
Local hour in 24-hour format. |
$mi, $ss, $tt |
Minutes, seconds and AM/PM designator. |
$timestamp, $date, $time |
Local time formatted as yyyyMMdd_HHmmss, yyyy-MM-dd and HH-mm-ss. |
$completefilename |
Alias for the current file path. |
$completefoldername |
Alias for the current folder path. |
$(Variable.@), $(Variable.Config) |
PDM file variable value for the current file. Use .@ for the file @ tab. |
$(Variable) |
PDM variable using the default configuration: @ for SOLIDWORKS parts/assemblies, empty configuration for other files; folder variable for a folder target. |
${global.Name} |
A session global variable. See Global variables. |
${local.Name} |
A variable set within this script, for example by a file/folder picker. Nested scripts have separate local variables. |
Use an explicit configuration suffix when you need a particular data-card tab: $(Description.@) for @, or $(PartNo.Default) for Default. Bracketed text such as [Description] is literal, not a PDM variable expression.
For scripts triggered by PDM, additional placeholders include $configuration, $fromState, $toState, $transition, $eventPath, $sourcePath and $destinationPath. They describe the triggering event and are empty when that information is unavailable. See the event placeholder reference for the complete list and examples. Selecting files with -search does not create an event.
Workflow values and event snapshots are different: $state describes the file context, while $fromState and $toState describe the original transition. Keep item-specific arguments on each command when processing multiple targets.
Example
The source script can use file placeholders and conditions. When the script is run for multiple items, these lines are evaluated for each target item.
RunTask -filePath "$localPath" -taskName "Publish PDF & DXF"
until -conditions "$folderPath\$fileNameWithoutExtension.pdf exists" -filePath "$localPath" -timeout 500
until -conditions "\"$(Description.@)\" equals A" -filePath "$localPath" -timeout 600
Free version limit
The free version is limited to 5 lines per script.
Search results report
runscript -source "C:\Vault\Scripts\CreateECO.pdmshell" -search "Name=%.sldprt" -recursive -csv "C:\Reports\results.csv"
The columns are ID, ParentFolderID, Name, Output, Status, Error, Exception and HRESULT. Each executed script step has a row for its target file; conditional steps that did not run are not reported as successes. Lines without a file target can have blank identity columns.
-csv requires -search and cannot be combined with -filePath, -id or -items. The report folder must exist. New vault reports are added to PDM; existing vault reports must be checked out by you on this computer and remain checked out. External reports are replaced. Relative report paths use the current vault folder. See CSV operation reports for failure handling and other reporting rules.
Standalone exit code
When the standalone pdmcli.exe process closes, it returns 0 for success or 1 if a command/script failed or was canceled. Failures remain recorded for that process: a later successful command or quit -silent does not clear them. Warnings explicitly ignored by script settings do not count as failures.
End an automation script with quit -silent to close PDMShell when it reaches that line. For example, save this as Inspect.pdmshell:
fileinfo -filePath "C:\Vault\Parts\1001.sldprt"
quit -silent
Connect to the vault as usual, or configure automatic login for the account running the script. Launch a separate process and wait for it before reading the result. In PowerShell:
$process = Start-Process -FilePath "C:\Path\To\pdmcli.exe" -ArgumentList '"C:\Vault\Scripts\Inspect.pdmshell"' -Wait -PassThru
$process.ExitCode
Replace the example executable, script and vault paths with your own. Do not use -single for this pattern: forwarding commands to an already-running window does not wait for that window's script result.
The exit code is available only after PDMShell closes. If execution stops before reaching quit, close the application to receive the result. -silent does not change the success/failure code. Add-in tasks report their result through PDM rather than through a standalone process exit code.