checkout
Description
Performs a check out operation on a specified file or many files.
Syntax
checkout -search -recursive -filePath -checkoutOptions
Use -id as an alternative to -filePath for the same operand. A required target still needs one selector, even though each alternative is optional individually. See File IDs and paths for selection rules and command-specific exceptions.
Parameters
| Parameter | Alias | Required | Description |
|---|---|---|---|
-search |
-s |
No | Search keyword |
-recursive |
No | Recursively check out all files in the current directory. Use in combination with search | |
-filePath (default) |
-f |
No | The file(s) to be checked out. This is the default parameter |
-checkoutOptions |
No | Use this to check a file and its references at once: | |
-id |
No | Positive PDM file ID instead of -filePath, identifying the same file that -filePath describes (including a macro, input CSV or existing output file). Requires a connected vault. Shared files with multiple locations require an exact -filePath. Resolving the ID itself does not download, check out or check in the file; the requested command still performs its normal operation. |
Parameter values
| Option Name (CLI) | Description |
|---|---|
| Nothing | No checkout options are applied. |
| AsBuilt1 | Uses the same versions of referenced files that were used when the referencing file was checked in; otherwise, the latest versions are used. |
| SkipUnlockedWritable | Does not retrieve files that are writable and not checked out. |
| SkipExisting | Does not retrieve files that already exist in the local cache. |
| ForPreview | Retrieves only referenced files required for preview; skips caching referenced files. |
| RefreshFileListing | Refreshes the File Explorer listing after files have been checked out. |
| LockReferencedFilesToo | Checks out (locks) files referenced by the checked-out file. |
| AsBuiltNotDefault | Uses the as-built versions when creating the reference tree. |
| SkipOpenFileChecks | Skips checking whether files are open in another application. |
| SkipLockRefFiles | Skips checking of lock file references. |
| LockNoLclCopyFiles | Locks referenced files even if no local cache copy exists. |
| IncludeAutoCacheFiles | Automatically caches referenced files if the latest version is not already in the local cache. |
| RollbackTree | Provides the ability to roll back files in the checkout dialog. |
| ForViewer | Retrieves only referenced files required by the viewer; skips caching referenced files. |
| SingleFileRollback | Rolls back a single file. |
| XrefsOpenCheck | Checks whether cross-reference files are open in another application. |
You combine values by using +. Please make sure to wrap the parameter value in "". Example: "SkipExisting + LockReferencedFilesToo"
Examples
checkout -filePath file1.sldprt
Remarks
Checkout refreshes the file and verifies that it is checked out by the executing user on this computer before reporting success. This applies to both -filePath and -search. A failed checkout is a command error and can make a PDM task fail.
A file already checked out by the executing user on the same computer is a successful skip, not an error. No ignore setting is required for this case. Another user's checkout, a checkout on another computer, permissions errors, and database/connection failures remain errors.
In task Error handling or vault script Handling, missing checkout targets can still be treated as warnings explicitly. Ignored conditions remain in the log; a command with only ignored conditions reports Command completed with warnings. Successful already-owned skips also apply to interactive commands.
- The search parameter searches the current directory and does not drill down. The search query is a PDM one, so you can use
%for wildcard.
Tutorial
Search results report
Add -csv "C:\Reports\results.csv" when using -search to save operation results. The first columns are file ID, parent folder ID, file name and output, followed by status and error details. 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. See CSV operation reports for command-specific outcomes.