@powerhousedao/academy 4.1.0-dev.10 → 4.1.0-dev.100

package/docs/academy/04-APIReferences/00-PowerhouseCLI.md

@@ -1,24 +1,58 @@
 # Powerhouse CLI
 
-### Installing the Powerhouse CLI 
+### Installing the Powerhouse CLI
+
 :::tip
-The **Powerhouse CLI tool** is the only essential tool to install on this page. Install it with the command below.    
+The **Powerhouse CLI tool** is the only essential tool to install on this page. Install it with the command below.
 
-You can find all of the commands on this page, similar to what would displayed when using ph --help or ph *command* --help. 
-Use the table of content or the search function to find what you are looking for.   
+You can find all of the commands on this page, similar to what would displayed when using ph --help or ph _command_ --help.
+Use the table of content or the search function to find what you are looking for.
 
 The Powerhouse CLI (`ph-cmd`) is a command-line interface tool that provides essential commands for managing Powerhouse projects. You can get access to the Powerhouse ecosystem tools by installing them globally.
 
 ```bash
 pnpm install -g ph-cmd
-``` 
- :::
+```
 
-<!-- AUTO-GENERATED-CLI-COMMANDS-START -->\n<!-- This content is automatically generated. Do not edit directly. -->\n### ph-cmd Commands\n\n- [Init](#init)
+:::
+
+<!-- AUTO-GENERATED-CLI-COMMANDS-START -->\n<!-- This content is automatically generated. Do not edit directly. -->\n### ph-cmd Commands\n\n- [Checkout](#checkout)
+- [Init](#init)
 - [Setup Globals](#setup-globals)
 - [Update](#update)
 - [Use](#use)
 
+## Checkout
+
+```
+Command Overview:
+  The checkout command clones an existing Powerhouse project from a remote Vetra drive.
+  This allows you to work on projects that have been initialized and configured by others.
+
+  This command:
+  1. Fetches the GitHub repository URL from the specified Vetra remote drive
+  2. Clones the repository to your local machine
+  3. Installs all project dependencies
+
+Required Options:
+  -r, --remote-drive <url>   URL of the Vetra remote drive containing the project.
+                             The drive must have a Vetra package with a configured GitHub URL.
+
+Options:
+  --package-manager <pm>     Specify which package manager to use for installing dependencies.
+                             Supported: npm, yarn, pnpm, bun
+                             If not specified, uses the detected package manager from your environment.
+
+Examples:
+  $ ph checkout --remote-drive https://vetra.example.com/d/abc123                  # Clone project using default package manager
+  $ ph checkout --remote-drive https://vetra.example.com/d/abc123 --package-manager pnpm   # Clone and install with pnpm
+
+Notes:
+  - The remote drive must contain a Vetra package document with a GitHub URL configured
+  - If no GitHub URL is found, you'll need to use 'ph init --remote-drive' instead to create a new project
+  - The repository will be cloned into a directory named after the repository
+```
+
 ## Init
 
 ```
@@ -42,12 +76,14 @@ Options:
                         
   -i, --interactive     Run the command in interactive mode, which will guide you
                         through the project setup with customizable options.
+  
+  -t, --tag             Version of the Powerhouse dependencies to use. Defaults to "main"
                         
-  -v, --version         Specify the development version to use. Defaults to "main".
-                        
-  --dev                 Use the "development" version of the boilerplate.
+  --dev                 Use the "development" version.
                         
-  --staging             Use the "staging" version of the boilerplate.
+  --staging             Use the "staging" version.
+
+  -b, --branch          Specify custom boilerplate branch to use.
                         
   --package-manager     Override the auto-detected package manager with the specified one.
 
@@ -226,15 +262,30 @@ Examples:
 
 ```
 Command Overview:
-  The Connect build command creates a connect build with the project's local and external packages included.
+  The Connect build command creates a production build with the project's local and
+  external packages included.
 
 Options:
-  --base <path> The base path for the app. Default is "/".
-  --project-root <path>  The root directory of the project. Default is "process.cwd()".
-  --assets-dir-name <name> The name of the assets directory. Default is "${DEFAULT_ASSETS_DIR_NAME}".
-  --external-packages-file-name <name> The name of the external packages file. Default is "${DEFAULT_EXTERNAL_PACKAGES_FILE_NAME}".
-  --styles-file-name <name> The name of the styles file. Default is "${DEFAULT_STYLES_FILE_NAME}".
-  --connect-path <path>  The path to the Connect dist directory. Calls "resolveConnect()" if not provided.
+  --outDir <outDir>           Output directory. Defaults to 'dist'.
+
+  --base <base>               Base path for the app. Default is "/".
+
+  --mode <mode>               Vite mode to use (e.g., development, production).
+
+  --config-file <configFile>  Path to the powerhouse.config.js file.
+
+  --vite-config-file <file>   Path to the vite config file.
+
+  --project-root <path>       The root directory of the project. Default is current directory.
+
+Examples:
+  $ ph connect build                              # Build with defaults
+  $ ph connect build --outDir build               # Output to 'build' directory
+  $ ph connect build --base /app                  # Set base path to '/app'
+  $ ph connect build --mode production            # Use production mode
+  $ ph connect build --config-file custom.config.js # Use custom configuration
+  $ ph connect build --vite-config-file vite.config.js # Use custom vite config
+  $ ph connect build --project-root /path/to/project # Set project root
 ```
 
 ## Connect Preview
@@ -245,10 +296,38 @@ Command Overview:
   NOTE: You must run \`ph connect build\` first.
 
 Options:
-  --base <path>          The base path for the app. Default is "/".
-  --project-root <path>  The root directory of the project. Default is "process.cwd()".
-  --port <port>          The port to run the server on. Default is 4173.
-  --open                 Open the browser. Default is true.
+  --outDir <outDir>           Output directory. Defaults to 'dist'.
+
+  --port <port>               Port to run the server on. Default is 3000.
+
+  --host                      Expose the server to the network.
+
+  --open                      Open browser on startup.
+
+  --strictPort                Exit if specified port is already in use.
+
+  --base <base>               Base path for the app. Default is "/".
+
+  --mode <mode>               Vite mode to use (e.g., development, production).
+
+  --config-file <configFile>  Path to the powerhouse.config.js file.
+
+  --vite-config-file <file>   Path to the vite config file.
+
+  --project-root <path>       The root directory of the project. Default is current directory.
+
+Examples:
+  $ ph connect preview                            # Preview with defaults
+  $ ph connect preview --outDir build             # Preview from 'build' directory
+  $ ph connect preview --port 8080                # Preview on port 8080
+  $ ph connect preview --host                     # Expose to network
+  $ ph connect preview --open                     # Open browser automatically
+  $ ph connect preview --strictPort               # Exit if port is in use
+  $ ph connect preview --base /app                # Set base path to '/app'
+  $ ph connect preview --mode production          # Use production mode
+  $ ph connect preview --config-file custom.config.js # Use custom configuration
+  $ ph connect preview --vite-config-file vite.config.js # Use custom vite config
+  $ ph connect preview --project-root /path/to/project # Set project root
 ```
 
 ## Connect Studio
@@ -256,7 +335,7 @@ Options:
 ```
 Command Overview:
   The connect command starts the Connect Studio, a development environment for building
-  and testing Powerhouse applications. It provides a visual interface for working with 
+  and testing Powerhouse applications. It provides a visual interface for working with
   your project.
 
   This command:
@@ -266,27 +345,41 @@ Command Overview:
   4. Supports various configuration options for customization
 
 Options:
-  -p, --port <port>      Port to run the server on. Default is 3000.
-                       
-  -h, --host             Expose the server to the network. By default, the server
-                        only accepts connections from localhost.
-                       
-  --https                Enable HTTPS for secure connections. You may need to provide
-                        certificate files for this option to work properly.
-                       
-  --open                 Automatically open the browser window after starting the server.
-                       
-  --config-file <path>   Path to the powerhouse.config.js file. This allows you to
-                        customize the behavior of Connect Studio.
+  --port <port>               Port to run the server on. Default is 3000.
+
+  --host                      Expose the server to the network. By default, the server
+                              only accepts connections from localhost.
+
+  --open                      Automatically open the browser window after starting the server.
+
+  --cors                      Enable CORS (Cross-Origin Resource Sharing).
+
+  --strictPort                Exit if specified port is already in use.
+
+  --force                     Force the optimizer to ignore the cache and re-bundle.
+
+  --mode <mode>               Vite mode to use (e.g., development, production).
+
+  --config-file <configFile>  Path to the powerhouse.config.js file. This allows you to
+                              customize the behavior of Connect Studio.
+
+  --vite-config-file <file>   Path to the vite config file.
+
+  --project-root <path>       The root directory of the project. Default is current directory.
 
 Examples:
-  $ ph connect                                # Start Connect Studio on default port 3000
-  $ ph connect -p 8080                        # Start on port 8080
-  $ ph connect -h                             # Expose to network (not just localhost)
-  $ ph connect --https                        # Enable HTTPS
-  $ ph connect --open                         # Open browser automatically
-  $ ph connect --config-file custom.config.js # Use custom configuration
-  $ ph connect -p 8080 --open                 # Start on port 8080 and open browser
+  $ ph connect                                 # Start Connect Studio on default port 3000
+  $ ph connect --port 8080                     # Start on port 8080
+  $ ph connect --host                          # Expose to network (not just localhost)
+  $ ph connect --open                          # Open browser automatically
+  $ ph connect --cors                          # Enable CORS
+  $ ph connect --strictPort                    # Exit if port is in use
+  $ ph connect --force                         # Force re-bundle
+  $ ph connect --mode production               # Use production mode
+  $ ph connect --config-file custom.config.js  # Use custom configuration
+  $ ph connect --vite-config-file vite.config.js # Use custom vite config
+  $ ph connect --project-root /path/to/project # Set project root
+  $ ph connect --port 8080 --open              # Start on port 8080 and open browser
 ```
 
 ## Dev
@@ -361,7 +454,7 @@ Options:
                         
   -p, --processor <name> Name of the processor to generate.
                         
-  --processor-type <type> Type of processor to generate.
+  --processor-type <type> Type of processor to generate. 'relationalDb' or 'analytics'
                         
   -s, --subgraph <name>  Name of the subgraph to use or create.
                         
@@ -388,7 +481,7 @@ Examples:
   $ ph generate my-document-model.zip                               # Generate from a specific model zip file
   $ ph generate -i                                                  # Run in interactive mode
   $ ph generate --editor ToDoList --document-types powerhouse/todo  # Generate a ToDoList editor for todo documents
-  $ ph generate -p MyProcessor                                      # Generate a specific processor
+  $ ph generate -p MyProcessor --processor-type relationalDb        # Generate a specific processor
   $ ph generate --watch                                             # Generate and watch for changes
   $ ph generate --drive-editor custom-drive-explorer                # Generate a custom drive editor
   $ ph generate -s MySubgraph                                       # Generate with a specific subgraph
@@ -611,6 +704,10 @@ Options:
   --config-file <path>    Path to the powerhouse.config.js file. Default is 
                         './powerhouse.config.json'. This configures the switchboard behavior.
                         
+  --dev                   Enable development mode to load local packages from the current directory.
+                        This allows the switchboard to discover and load document models, processors,
+                        and subgraphs from your local development environment.
+                        
   --db-path <DB_PATH>     Path to the database for storing document data.
                         
   --https-key-file <path> Path to the SSL key file if using HTTPS for secure connections.
@@ -626,6 +723,7 @@ Options:
 Examples:
   $ ph switchboard                           # Start switchboard with default settings
   $ ph switchboard --port 5000               # Use custom port 5000
+  $ ph switchboard --dev                     # Enable dev mode to load local packages
   $ ph switchboard --config-file custom.json # Use custom configuration file
   $ ph switchboard --packages pkg1 pkg2      # Load specific packages
   $ ph switchboard --base-path /switchboard  # Set API base path to /switchboard
@@ -709,45 +807,60 @@ Notes:
 
 ```
 Command Overview:
-  The vetra command sets up a complete Vetra development environment for working with Vetra projects.
-  It starts three coordinated services: a Vetra Switchboard, a Local Reactor, and Connect Studio,
-  enabling full document collaboration and real-time processing with a "Vetra" drive.
+  The vetra command sets up a Vetra development environment for working with Vetra projects.
+  It starts a Vetra Switchboard and optionally Connect Studio, enabling document collaboration 
+  and real-time processing with a "Vetra" drive or connection to remote drives.
 
   This command:
   1. Starts a Vetra Switchboard with a "Vetra" drive for document storage
-  2. Starts a Local Reactor that connects to the Vetra Switchboard as a remote drive
-  3. Starts Connect Studio pointing to the Local Reactor for user interaction
-  4. Enables real-time updates, collaboration, and code generation across all services
+  2. Optionally connects to remote drives instead of creating a local drive
+  3. Starts Connect Studio pointing to the Switchboard for user interaction (unless disabled)
+  4. Enables real-time updates, collaboration, and code generation
 
 Options:
-  --generate               Generate code automatically when document models are updated.
-                          This keeps your code in sync with model changes across all services.
+  --logs                     Enable verbose logging for all services. This provides detailed
+                            output from Switchboard and Connect during startup and operation.
                         
-  --switchboard-port <port> Specify the port to use for the Vetra Switchboard service.
-                          Default is 4001. The Switchboard handles document storage.
+  --switchboard-port <port>  Specify the port to use for the Vetra Switchboard service.
+                            Default is 4001. The Switchboard handles document storage.
                         
-  --reactor-port <port>    Specify the port to use for the Local Reactor service.
-                          Default is 4002. The Reactor provides the main API and connects to switchboard.
+  --connect-port <port>      Specify the port to use for Connect Studio.
+                            Default is 3000. Connect provides the user interface.
                         
-  --https-key-file <path>  Path to the SSL key file if using HTTPS for secure connections.
+  --https-key-file <path>    Path to the SSL key file if using HTTPS for secure connections.
                         
-  --https-cert-file <path> Path to the SSL certificate file if using HTTPS.
+  --https-cert-file <path>   Path to the SSL certificate file if using HTTPS.
                         
-  --config-file <path>     Path to the powerhouse.config.js file. This allows you to
-                          customize the behavior of all services in the Vetra development environment.
+  --config-file <path>       Path to the powerhouse.config.js file. This allows you to
+                            customize the behavior of the Vetra development environment.
                         
-  -w, --watch              Watch for local changes to document models and processors,
-                          and automatically update both the Switchboard and Reactor accordingly.
+  -w, --watch                Enable dynamic loading for document-models and editors in
+                            connect-studio and switchboard. When enabled, the system will
+                            watch for changes in these directories and reload them dynamically.
+                        
+  --remote-drive <url>       URL of remote drive to connect to. When specified, the switchboard
+                            connects to this remote drive instead of creating a local Vetra drive.
+                        
+  --disable-connect          Skip Connect initialization (only start switchboard and reactor).
+                            Use this when you only need the backend services running.
+                        
+  --interactive              Enable interactive mode for code generation. When enabled, the system
+                            will prompt for user confirmation before generating code. This is useful
+                            for development when you want control over when code regeneration happens.
 
 Examples:
-  $ ph vetra                                           # Start complete Vetra environment with defaults
-  $ ph vetra --generate                                # Auto-generate code on model changes
-  $ ph vetra --switchboard-port 5000 --reactor-port 5001  # Use custom ports
-  $ ph vetra --config-file custom.powerhouse.config.js # Use custom configuration
-  $ ph vetra --watch                                   # Watch for changes and auto-update
+  $ ph vetra                                              # Start Vetra environment with defaults
+  $ ph vetra --switchboard-port 5000 --connect-port 3001 # Use custom ports
+  $ ph vetra --config-file custom.powerhouse.config.js   # Use custom configuration
+  $ ph vetra --watch                                      # Enable dynamic loading for development
+  $ ph vetra -w                                           # Enable dynamic loading (short form)
+  $ ph vetra --logs                                       # Enable detailed logging
+  $ ph vetra --remote-drive http://localhost:4001/d/docs  # Connect to remote drive
+  $ ph vetra --disable-connect                            # Start only backend services
+  $ ph vetra --interactive                                # Enable interactive code generation mode
   $ ph vetra --https-key-file key.pem --https-cert-file cert.pem  # Use HTTPS
 ```
 
 ---
 
-*This document was automatically generated from the help text in the codebase.*\n<!-- AUTO-GENERATED-CLI-COMMANDS-END -->
+*This document was automatically generated from the help text in the codebase.*\n<!-- AUTO-GENERATED-CLI-COMMANDS-END -->