Powerhouse CLI
Installing the Powerhouse CLI
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.
The Powerhouse CLI (ph-cmd) is a command-line interface tool that provides essential commands for managing Powerhouse Vetra projects. You can get access to the Powerhouse ecosystem tools by installing them globally.
pnpm install -g ph-cmd
Quick Reference
| Command | Description | Example |
|---|---|---|
ph init | Initialize a new project | ph init my-project --pnpm |
ph use | Switch to a release version | ph use staging |
ph update | Update dependencies to latest | ph update |
ph setup-globals | Initialize global project | ph setup-globals my-globals |
ph use-local | Use local monorepo dependencies | ph use-local ../powerhouse |
ph-cmd Commands
Init
Initialize a new project
Parameters
Arguments
Name - The name of your project. A new directory will be created in your current directory with this name. - Usage: [name]
Options
Name - The name of your project. A new directory will be created in your current directory with this name. - Usage: --name, -n <str>
Package Manager - Specify the package manager to use for your project. Can be one of: npm, pnpm, yarn, or bun. Defaults to your environment package manager. - Usage: --package-manager, -p <value>
Tag - Specify the release tag to use for your project. Can be one of: "latest", "staging", or "dev". - Usage: --tag, -t <value>
Version - Specify the exact semver release version to use for your project. - Usage: --version, -v <str>
Remote Drive - Remote drive identifier. - Usage: --remote-drive, -r <str>
Flags
Npm - Use 'npm' as package manager - Usage: --npm
Pnpm - Use 'pnpm' as package manager - Usage: --pnpm
Yarn - Use 'yarn' as package manager - Usage: --yarn
Bun - Use 'bun' as package manager - Usage: --bun
Dev - Use the dev release tag. - Usage: --dev, -d
Staging - Use the staging release tag. - Usage: --staging, -s
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Use
Specify the release version of Powerhouse dependencies to use.
Parameters
Arguments
Tag - Specify the release tag to use for your project. Can be one of: "latest", "staging", or "dev". - Usage: [tag]
Options
Tag - Specify the release tag to use for your project. Can be one of: "latest", "staging", or "dev". - Usage: --tag, -t <value>
Version - Specify the exact semver release version to use for your project. - Usage: --version, -v <str>
Flags
Skip Install - Skip running install with your package manager - Usage: --skip-install, -s
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Update
Update your powerhouse dependencies to their latest tagged version
Flags
Skip Install - Skip running install with your package manager - Usage: --skip-install, -s
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Setup Globals
Initialize a new global project
Parameters
Arguments
Name - The name of your project. A new directory will be created in your current directory with this name. - Usage: [name]
Options
Name - The name of your project. A new directory will be created in your current directory with this name. - Usage: --name, -n <str>
Package Manager - Specify the package manager to use for your project. Can be one of: npm, pnpm, yarn, or bun. Defaults to your environment package manager. - Usage: --package-manager, -p <value>
Tag - Specify the release tag to use for your project. Can be one of: "latest", "staging", or "dev". - Usage: --tag, -t <value>
Version - Specify the exact semver release version to use for your project. - Usage: --version, -v <str>
Remote Drive - Remote drive identifier. - Usage: --remote-drive, -r <str>
Flags
Npm - Use 'npm' as package manager - Usage: --npm
Pnpm - Use 'pnpm' as package manager - Usage: --pnpm
Yarn - Use 'yarn' as package manager - Usage: --yarn
Bun - Use 'bun' as package manager - Usage: --bun
Dev - Use the dev release tag. - Usage: --dev, -d
Staging - Use the staging release tag. - Usage: --staging, -s
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Use Local
Use your local powerhouse monorepo dependencies the current project.
Parameters
Arguments
Monorepo Path - Path to your local powerhouse monorepo relative to this project - Usage: [monorepo path]
Options
Path - Path to your local powerhouse monorepo relative to this project - Usage: --path, -p <str>
Flags
Skip Install - Skip running install with pnpm - Usage: --skip-install, -s
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
ph-cli Commands
- Generate
- All
- Document Model
- Editor
- App
- Processor
- Subgraph
- Migration File
- Vetra
- Connect
- Connect Studio
- Connect Build
- Connect Preview
- Access Token
- Inspect
- List
- Migrate
- Switchboard
- Login
- Install
- Uninstall
Generate
The generate command creates code for Powerhouse modules. It helps you create new code from scratch, or to re-generate existing code in your project.
All
Re-generate all modules in the current project
Flags
Help - show help - Usage: --help, -h
Document Model
Generate a document model
Options
File - Path to the file to generate the document model from - Usage: --file, -f <file>
Dir - Name of the directory of an existing document model to re-generate - Usage: --dir, -d <dir>
Flags
All - Re-generate all existing document models in the current project - Usage: --all, -a
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Editor
Generate a document editor
Options
Name - The name of the document editor to generate - Usage: --name, -n <str>
Document Type - The document type for the new editor - Usage: --document-type, -t <str>
Dir - Name of the directory of an existing editor to re-generate - Usage: --dir, -d <dir>
Flags
All - Re-generate all existing editors in the current project - Usage: --all, -a
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
App
Generate a drive app
Options
Name - The name of the drive app to generate - Usage: --name, -n <str>
Document Types - The document types allowed by the new app - Usage: --document-types <str>, -t=<str>
Dir - Name of the directory of an existing app to re-generate - Usage: --dir, -d <dir>
Flags
Disable Drag And Drop - Do not allow drag and drop in this drive app. - Usage: --disable-drag-and-drop
Default: false
All - Re-generate all existing apps in the current project - Usage: --all, -a
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Processor
Generate a processor
Options
Name - The name of the processor to generate - Usage: --name, -n <str>
Type - The type of processor to generate - Usage: --type <value>
Default: analytics
Document Types - The document types the processor will run on - Usage: --document-types <str>, -t=<str>
Default: ``
Apps - Whether the processor will run in switchboard (nodejs), connect (browser), or both - Usage: --apps <value>
Default: switchboard,connect
Dir - Name of the directory of an existing processor to re-generate - Usage: --dir, -d <dir>
Flags
All - Re-generate all existing processors in the current project - Usage: --all, -a
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Subgraph
Generate a subgraph
Options
Name - The name of the subgraph to generate - Usage: --name, -n <str>
Dir - Name of the directory of an existing subgraph to re-generate - Usage: --dir, -d <dir>
Flags
All - Re-generate all existing subgraphs in the current project - Usage: --all, -a
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Migration File
Generate a migration file
Options
Path [required] - Path to the migration file - Usage: --path, -p <str>
Schema File - Path to the output file. Defaults to './schema.ts' - Usage: --schema-file <str>
Flags
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Vetra
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.
What it does:
-
- Starts a Vetra Switchboard with a "Vetra" drive for document storage
-
- Optionally connects to remote drives instead of creating a local drive
-
- Starts Connect Studio pointing to the Switchboard for user interaction (unless disabled)
-
- Enables real-time updates, collaboration, and code generation
Options
Switchboard Port - port to use for the Vetra Switchboard - Usage: --switchboard-port <number>
Connect Port - port to use for the Vetra Connect - Usage: --connect-port <number>
Default: 3001
Remote Drive - URL of remote drive to connect to (skips switchboard initialization) - Usage: --remote-drive <str>
Base - Base path for the app - Usage: --base <str>
Environment: PH_CONNECT_BASE_PATH
Log Level - Log level for the application - Usage: --log-level <value>
Environment: PH_CONNECT_LOG_LEVEL
Default: info
Packages - Comma-separated list of package names to load - Usage: --packages <str>
Environment: PH_PACKAGES
Local Package - Path to local package to load during development - Usage: --local-package <str>
Environment: PH_LOCAL_PACKAGE
Default Drives Url - The default drives url to use in connect - Usage: --default-drives-url <str>
Environment: PH_CONNECT_DEFAULT_DRIVES_URL
Drive Preserve Strategy - The preservation strategy to use on default drives - Usage: --drive-preserve-strategy <value>
Environment: PH_CONNECT_DRIVES_PRESERVE_STRATEGY
Default: preserve-by-url-and-detach
Watch Timeout - Amount of time to wait before a file is considered changed - Usage: --watch-timeout <number>
Environment: PH_WATCH_TIMEOUT
Default: 300
Https Key File - path to the ssl key file - Usage: --https-key-file <str>
Https Cert File - path to the ssl cert file - Usage: --https-cert-file <str>
Remote Drives - Specify remote drive URLs to use - Usage: --remote-drives <str>
Flags
Watch - Enable dynamic loading for document-models and editors in connect-studio and switchboard - Usage: --watch, -w
Default: false
Logs - Show additional logs - Usage: --logs
Default: false
Disable Connect - Skip Connect initialization (only start switchboard and reactor) - Usage: --disable-connect
Default: false
Interactive - Enable interactive mode for code generation (requires user confirmation before generating code) - Usage: --interactive
Default: false
Ignore Local - Do not load local packages from this project - Usage: --ignore-local
Environment: PH_DISABLE_LOCAL_PACKAGE
Force - Force dep pre-optimization regardless of whether deps have changed. - Usage: --force
Debug - Log arguments passed to this command - Usage: --debug
Host - Expose the server to the network - Usage: --host
Open - Open browser on startup - Usage: --open
Cors - Enable CORS - Usage: --cors
Strict Port - Exit if specified port is already in use - Usage: --strictPort
Print Urls - Print server urls - Usage: --print-urls
Default: true
Bind Cli Shortcuts - Bind CLI shortcuts - Usage: --bind-cli-shortcuts
Default: true
Https - Use https - Usage: --https
Dev - enable development mode to load local packages - Usage: --dev
Help - show help - Usage: --help, -h
Connect
Powerhouse Connect commands. Use with studio, build or preview. Defaults to studio if not specified.
Connect Studio
The studio command starts the Connect Studio, a development environment for building and testing Powerhouse applications. It provides a visual interface for working with your project.
What it does:
-
- Starts a local Connect Studio server
-
- Provides a web interface for development
-
- Allows you to interact with your project components
-
- Supports various configuration options for customization
Options
Port - Port to run the dev server on. - Usage: --port <number>
Default: 3000
Base - Base path for the app - Usage: --base <str>
Environment: PH_CONNECT_BASE_PATH
Log Level - Log level for the application - Usage: --log-level <value>
Environment: PH_CONNECT_LOG_LEVEL
Default: info
Packages - Comma-separated list of package names to load - Usage: --packages <str>
Environment: PH_PACKAGES
Local Package - Path to local package to load during development - Usage: --local-package <str>
Environment: PH_LOCAL_PACKAGE
Default Drives Url - The default drives url to use in connect - Usage: --default-drives-url <str>
Environment: PH_CONNECT_DEFAULT_DRIVES_URL
Drive Preserve Strategy - The preservation strategy to use on default drives - Usage: --drive-preserve-strategy <value>
Environment: PH_CONNECT_DRIVES_PRESERVE_STRATEGY
Default: preserve-by-url-and-detach
Watch Timeout - Amount of time to wait before a file is considered changed - Usage: --watch-timeout <number>
Environment: PH_WATCH_TIMEOUT
Default: 300
Flags
Ignore Local - Do not load local packages from this project - Usage: --ignore-local
Environment: PH_DISABLE_LOCAL_PACKAGE
Force - Force dep pre-optimization regardless of whether deps have changed. - Usage: --force
Debug - Log arguments passed to this command - Usage: --debug
Host - Expose the server to the network - Usage: --host
Open - Open browser on startup - Usage: --open
Cors - Enable CORS - Usage: --cors
Strict Port - Exit if specified port is already in use - Usage: --strictPort
Print Urls - Print server urls - Usage: --print-urls
Default: true
Bind Cli Shortcuts - Bind CLI shortcuts - Usage: --bind-cli-shortcuts
Default: true
Help - show help - Usage: --help, -h
Connect Build
The Connect build command creates a production build with the project's local and external packages included
Options
Out Dir - Output directory - Usage: --outDir <str>
Default: .ph/connect-build/dist/
Base - Base path for the app - Usage: --base <str>
Environment: PH_CONNECT_BASE_PATH
Log Level - Log level for the application - Usage: --log-level <value>
Environment: PH_CONNECT_LOG_LEVEL
Default: info
Packages - Comma-separated list of package names to load - Usage: --packages <str>
Environment: PH_PACKAGES
Local Package - Path to local package to load during development - Usage: --local-package <str>
Environment: PH_LOCAL_PACKAGE
Default Drives Url - The default drives url to use in connect - Usage: --default-drives-url <str>
Environment: PH_CONNECT_DEFAULT_DRIVES_URL
Drive Preserve Strategy - The preservation strategy to use on default drives - Usage: --drive-preserve-strategy <value>
Environment: PH_CONNECT_DRIVES_PRESERVE_STRATEGY
Default: preserve-by-url-and-detach
Flags
Ignore Local - Do not load local packages from this project - Usage: --ignore-local
Environment: PH_DISABLE_LOCAL_PACKAGE
Force - Force dep pre-optimization regardless of whether deps have changed. - Usage: --force
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Connect Preview
The Connect preview command previews a built Connect project.
NOTE: You must run ph connect build first
Options
Port - Port to run the preview server on. - Usage: --port <number>
Default: 4173
Out Dir - Output directory - Usage: --outDir <str>
Default: .ph/connect-build/dist/
Base - Base path for the app - Usage: --base <str>
Environment: PH_CONNECT_BASE_PATH
Log Level - Log level for the application - Usage: --log-level <value>
Environment: PH_CONNECT_LOG_LEVEL
Default: info
Packages - Comma-separated list of package names to load - Usage: --packages <str>
Environment: PH_PACKAGES
Local Package - Path to local package to load during development - Usage: --local-package <str>
Environment: PH_LOCAL_PACKAGE
Default Drives Url - The default drives url to use in connect - Usage: --default-drives-url <str>
Environment: PH_CONNECT_DEFAULT_DRIVES_URL
Drive Preserve Strategy - The preservation strategy to use on default drives - Usage: --drive-preserve-strategy <value>
Environment: PH_CONNECT_DRIVES_PRESERVE_STRATEGY
Default: preserve-by-url-and-detach
Watch Timeout - Amount of time to wait before a file is considered changed - Usage: --watch-timeout <number>
Environment: PH_WATCH_TIMEOUT
Default: 300
Flags
Ignore Local - Do not load local packages from this project - Usage: --ignore-local
Environment: PH_DISABLE_LOCAL_PACKAGE
Force - Force dep pre-optimization regardless of whether deps have changed. - Usage: --force
Debug - Log arguments passed to this command - Usage: --debug
Host - Expose the server to the network - Usage: --host
Open - Open browser on startup - Usage: --open
Cors - Enable CORS - Usage: --cors
Strict Port - Exit if specified port is already in use - Usage: --strictPort
Print Urls - Print server urls - Usage: --print-urls
Default: true
Bind Cli Shortcuts - Bind CLI shortcuts - Usage: --bind-cli-shortcuts
Default: true
Help - show help - Usage: --help, -h
Access Token
The access-token command generates a bearer token for API authentication. This token can be used to authenticate requests to Powerhouse APIs like reactor-api (Switchboard).
What it does:
-
- Uses your CLI's cryptographic identity (DID) to sign a verifiable credential
-
- Creates a JWT bearer token with configurable expiration
-
- Outputs the token to stdout (info to stderr) for easy piping
Prerequisites: You must have a cryptographic identity. Run 'ph login' first to:
- Generate a keypair (stored in .ph/.keypair.json)
- Optionally link your Ethereum address (stored in .ph/.renown.json)
Token Details: The generated token is a JWT (JSON Web Token) containing:
- Issuer (iss): Your CLI's DID (did🔑...)
- Subject (sub): Your CLI's DID
- Credential Subject: Chain ID, network ID, and address (if authenticated)
- Expiration (exp): Based on --expiry option
- Audience (aud): If --audience is specified
Output:
- Token information (DID, address, expiry) is printed to stderr
- The token itself is printed to stdout for easy piping/copying
This allows you to use the command in scripts: TOKEN=$(ph access-token) curl -H "Authorization: Bearer $TOKEN" http://localhost:4001/graphql
Usage with APIs:
Generate token and use with curl
TOKEN=$(ph access-token --expiry 1d)
curl -X POST http://localhost:4001/graphql
-H "Content-Type: application/json"
-H "Authorization: Bearer $TOKEN"
-d '{"query": "{ drives { id name } }"}'
Export as environment variable export PH_ACCESS_TOKEN=$(ph access-token)
Notes:
- Tokens are self-signed using your CLI's private key
- No network request is made; tokens are generated locally
- The recipient API must trust your CLI's DID to accept the token
- For reactor-api, ensure AUTH_ENABLED=true to require authentication
Options
Expiry - Token expiry duration. Supports: "7d" (days), "24h" (hours), "3600" or "3600s" (seconds) - Usage: --expiry <str>
Default: 7d
Audience - Target audience URL for the token - Usage: --audience <str>
Flags
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Inspect
The inspect command examines and provides detailed information about a Powerhouse package. It helps you understand the structure, dependencies, and configuration of packages in your project.
What it does:
-
- Analyzes the specified package
-
- Retrieves detailed information about its structure and configuration
-
- Displays package metadata, dependencies, and other relevant information
-
- Helps troubleshoot package-related issues
Parameters
Arguments
Package Name [required] - The name of the package to inspect - Usage: <package-name>
Flags
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
List
The list command displays information about installed Powerhouse packages in your project. It reads the powerhouse.config.json file and shows the packages that are currently installed.
What it does:
-
- Examines your project configuration
-
- Lists all installed Powerhouse packages
-
- Provides a clear overview of your project's dependencies
-
- Helps you manage and track your Powerhouse components
Flags
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Migrate
Run migrations
Options
Version - The version to migrate to. Accepts a valid semver version or staging, dev, latest. - Usage: --version, -v <str>
Default: latest
Flags
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Switchboard
The switchboard command starts a local Switchboard instance, which acts as the document processing engine for Powerhouse projects. It provides the infrastructure for document models, processors, and real-time updates.
What it does:
-
- Starts a local switchboard server
-
- Loads document models and processors
-
- Provides an API for document operations
-
- Enables real-time document processing
-
- Can authenticate with remote services using your identity from 'ph login'
Flags
Https - Use https - Usage: --https
Dev - enable development mode to load local packages - Usage: --dev
Ignore Local - Do not load local packages from this project - Usage: --ignore-local
Environment: PH_DISABLE_LOCAL_PACKAGE
Debug - Log arguments passed to this command - Usage: --debug
Use Identity - enable identity using keypair from ph login (uses ~/.ph/keypair.json) - Usage: --use-identity
Require Identity - require existing keypair, fail if not found (implies --use-identity) - Usage: --require-identity
Migrate - Run database migrations and exit - Usage: --migrate
Migrate Status - Show migration status and exit - Usage: --migrate-status
Mcp - enable Mcp route at /mcp - Usage: --mcp
Default: true
Use Vetra Drive - Use a Vetra drive - Usage: --use-vetra-drive
Default: false
Help - show help - Usage: --help, -h
Options
Https Key File - path to the ssl key file - Usage: --https-key-file <str>
Https Cert File - path to the ssl cert file - Usage: --https-cert-file <str>
Remote Drives - Specify remote drive URLs to use - Usage: --remote-drives <str>
Packages - Comma-separated list of package names to load - Usage: --packages <str>
Environment: PH_PACKAGES
Port - Port to host the api - Usage: --port <number>
Default: 4001
Base Path - base path for the API endpoints (sets the BASE_PATH environment variable) - Usage: --base-path <str>
Keypair Path - path to custom keypair file for identity - Usage: --keypair-path <str>
Vetra Drive Id - Specify a Vetra drive ID - Usage: --vetra-drive-id <str>
Default: vetra
Db Path - path to the database - Usage: --db-path <str>
Login
The login command authenticates you with Renown using your Ethereum wallet. This enables the CLI to act on behalf of your Ethereum identity for authenticated operations.
What it does:
-
- Generates or loads a cryptographic identity (DID) for the CLI
-
- Opens your browser to the Renown authentication page
-
- You authorize the CLI's DID to act on behalf of your Ethereum address
-
- Stores the credentials locally in .ph/.renown.json
Options
Renown Url - Renown server URL. - Usage: --renown-url <str>
Environment: PH_CONNECT_RENOWN_URL
Default: https//www.renown.id
Timeout - Authentication timeout in seconds. - Usage: --timeout <number>
Default: 300
Flags
Logout - Sign out and clear stored credentials - Usage: --logout
Status - Show current authentication status - Usage: --status
Show Did - Show the CLI's DID and exit - Usage: --show-did
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Install
The install command adds Powerhouse dependencies to your project.
By default it only registers the package in powerhouse.config.json with provider "registry" — Connect will load it from the registry CDN at runtime.
With --local, the package is also installed into node_modules and marked as provider "local" — it will be bundled into ph connect build so the preview works without the registry being reachable.
Resolution order for the registry URL: --registry flag > PH_REGISTRY_URL env > powerhouse.config.json > default
Parameters
Arguments
Dependencies [required] - Names of the dependencies to install - Usage: [...dependencies]
Options
Registry - Registry URL to install from (overrides config and environment) - Usage: --registry <str>
Package Manager - Specify the package manager to use for your project. Can be one of: npm, pnpm, yarn, or bun. Defaults to your environment package manager. - Usage: --package-manager, -p <value>
Flags
Local - Also install packages into node_modules (marks them as provider: "local" so they get bundled into ph connect build) - Usage: --local
Npm - Use 'npm' as package manager - Usage: --npm
Pnpm - Use 'pnpm' as package manager - Usage: --pnpm
Yarn - Use 'yarn' as package manager - Usage: --yarn
Bun - Use 'bun' as package manager - Usage: --bun
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h
Uninstall
The uninstall command removes Powerhouse dependencies from your project. It handles the removal of packages, updates configuration files, and ensures proper cleanup.
What it does:
-
- Uninstalls specified Powerhouse dependencies using your package manager
-
- Updates powerhouse.config.json to remove the dependencies
-
- Supports various uninstallation options and configurations
-
- Works with npm, yarn, yarn@berry, pnpm, pnpm@6, bun, deno package managers
Parameters
Arguments
Dependencies [required] - Names of the dependencies to uninstall - Usage: [...dependencies]
Options
Package Manager - Specify the package manager to use for your project. Can be one of: npm, pnpm, yarn, or bun. Defaults to your environment package manager. - Usage: --package-manager, -p <value>
Flags
Npm - Use 'npm' as package manager - Usage: --npm
Pnpm - Use 'pnpm' as package manager - Usage: --pnpm
Yarn - Use 'yarn' as package manager - Usage: --yarn
Bun - Use 'bun' as package manager - Usage: --bun
Debug - Log arguments passed to this command - Usage: --debug
Help - show help - Usage: --help, -h