¶ PolyverseSync Command Line Tool
polyversesync is a powerful command-line tool designed to streamline the synchronization of 2D and 3D assets with the Polyverse platform. By leveraging the Polyverse API, it enables users to upload, manage, and synchronize files from a local folder to a Polyverse library efficiently. The tool supports file hashing, version control, and selective file imports, making it ideal for developers, artists, and teams working with 3D content in industries like game development, VFX, XR, and more.
¶ Installation
To install polyversesync, use npm:
npm install -g polyversesync
This installs the tool globally, allowing you to run it from any terminal.
If you do not have
npminstalled yet, you can download the latest version from the official NodeJS website.
¶ Overview
polyversesync reads files from a specified local folder, computes their hashes using the Blake3 algorithm, and uploads them to a designated Polyverse library. It maintains a local database to track synchronized files, preventing redundant uploads of unchanged files. Even without a local database, the tool can identify whether a file already exists in the Polyverse library by comparing hashes. For files with changes, polyversesync supports uploading new versions, provided the local database contains the previous hash. Additionally, it offers flexible import masks for selective file type imports and options to manage file deletions.
¶ Usage
Run polyversesync with the following syntax:
polyversesync [options]
¶ Options
| Option | Environment Variable | Description | Default |
|---|---|---|---|
-key <apikey> |
POLYVERSE_API_KEY |
Specifies the API key for authenticating with the Polyverse API. | None |
-library <libraryID> |
POLYVERSE_LIBRARY_ID |
Sets the target Polyverse library ID for uploads. | None |
-folder <folder> |
POLYVERSE_SOURCE_FOLDER |
Defines the source folder containing files to synchronize. | Current directory (.) |
-import <mask> |
POLYVERSE_IMPORT_MASK |
Specifies file types to import using masks (e.g., *.fbx, *.mp4). Multiple masks can be provided, separated by commas (e.g., *.fbx,*.mp4). |
None |
-delete <none/local/polyverse> |
POLYVERSE_DELETE_MODE |
Controls deletion behavior for files no longer in the source folder: - none: No deletions.- local: Deletes from the local database only.- polyverse: Deletes from both the local database and the Polyverse library. |
None |
-frontend <url> |
POLYVERSE_FRONTEND_URL |
Sets the Polyverse frontend URL. | https://hello.polyverse.cloud |
-backend <url> |
POLYVERSE_BACKEND_URL |
Sets the Polyverse backend API URL. | https://api.polyverse.cloud |
-h, --help |
N/A | Displays the help message with usage information. | N/A |
¶ Using Environment Variables
You can configure some options using environment variables, which take precedence over command-line arguments if both are provided. See the above table for the available environment variables.
To set environment variables, use the following syntax (example for Unix-based systems):
export POLYVERSE_API_KEY="myApiKey"
export POLYVERSE_LIBRARY_ID="myLibraryID"
export POLYVERSE_IMPORT_MASK="*.fbx,*.mp4"
polyversesync
On Windows (Command Prompt):
set POLYVERSE_API_KEY=myApiKey
set POLYVERSE_LIBRARY_ID=myLibraryID
set POLYVERSE_IMPORT_MASK=*.fbx,*.mp4
polyversesync
¶ Example Commands
-
Basic Synchronization with Command-Line Options:
Synchronize all.fbxfiles from the current directory to a Polyverse library:polyversesync -key myApiKey -library myLibraryID -import "*.fbx" -
Using Environment Variables:
Synchronize files using environment variables:export POLYVERSE_API_KEY="myApiKey" export POLYVERSE_LIBRARY_ID="myLibraryID" export POLYVERSE_IMPORT_MASK="*.fbx" polyversesync -
Multiple File Types:
Import both.fbxand.mp4files from a specific folder:polyversesync -key myApiKey -library myLibraryID -folder ./assets -import "*.fbx,*.mp4" -
Delete Mode:
Synchronize files and delete assets from the Polyverse library that no longer exist in the source folder:polyversesync -key myApiKey -library myLibraryID -folder ./assets -import "*.fbx" -delete polyverse -
Custom URLs:
Use custom frontend and backend URLs:polyversesync -key myApiKey -library myLibraryID -frontend https://custom.polyverse.cloud -backend https://custom-api.polyverse.cloud -import "*.fbx"
¶ Key Features
¶ File Hashing with Blake3
polyversesync uses the Blake3 hashing algorithm to generate unique identifiers for files. This ensures efficient comparison and prevents redundant uploads. If a file’s hash matches an existing asset in the Polyverse library, the tool skips the upload unless a new version is needed.
¶ Local Database
The tool maintains a local database to track synchronized files and their hashes. This database enables:
- Efficient Synchronization: Avoids re-uploading unchanged files.
- Version Control: When a file changes, the previous data (stored locally) is used to locate the asset in the Polyverse library, and the new version is uploaded as an update.
If no local database exists, polyversesync can still determine if a file is already uploaded by querying the Polyverse library with the file’s hash.
¶ Flexible Import Masks
Users can specify which file types to synchronize using import masks. For example:
*.fbximports all FBX files.*.fbx,*.mp4imports both FBX and MP4 files.
This feature allows precise control over which assets are processed.
¶ Deletion Modes
The -delete option provides flexibility in handling files that no longer exist in the source folder:
none: No action is taken.local: Removes entries from the local database but leaves the Polyverse library unchanged.polyverse: Deletes assets from both the local database and the Polyverse library.
¶ Versioning
When a file changes and the local database is available, polyversesync uses the previous hash to identify the asset in the Polyverse library and uploads the modified file as a new version. This ensures seamless version control without duplicating assets.
¶ Best Practices
- Secure API Keys: Store your API key securely, preferably in environment variables, to avoid exposing it in scripts or version control systems.
- Single Source of Truth: Avoid running the tool from multiple devices. Use a single device that performs regular runs.
- Regular Backups: Before using
-delete polyverse, back up critical assets to prevent accidental data loss. - Test Import Masks: Verify import masks (e.g.,
*.fbx,*.mp4) to ensure only intended file types are processed. - Custom URLs: Use custom frontend and backend URLs only when directed by your Polyverse administrator or documentation.
- Environment Variables: Use environment variables for sensitive or frequently used options like API keys to simplify command-line usage.
¶ Troubleshooting
- API Key Errors: Ensure the
-keyorPOLYVERSE_API_KEYvalue is valid and has appropriate permissions for the specified library. - Library ID Issues: Verify the
-libraryorPOLYVERSE_LIBRARY_IDmatches an existing Polyverse library. - File Not Found: Confirm the
-folderpath is correct and accessible. - Import Mask Problems: Check that the
-importorPOLYVERSE_IMPORT_MASKsyntax is correct (e.g., use commas to separate multiple masks). - Deletion Errors: If using
-delete polyverse, ensure you have sufficient permissions to delete assets from the library. - Asset Type Compatibility: Some asset types are only available in private libraries, ensure that your library is setup as private when issues arise.
For additional support, visit the Abstract Community or refer to the Polyverse Documentation.
¶ Conclusion
polyversesync is a versatile tool for automating asset synchronization with the Polyverse platform. Its support for file hashing, version control, import masks, deletion modes, and environment variables makes it an essential part of any 3D content workflow. Whether you’re a game developer, VFX artist, or XR creator, polyversesync simplifies the process of managing and sharing assets in the cloud.
For more information, explore the Polyverse Documentation or contact the Abstract team at https://theabstract.co.