CLI for Managing Phala Cloud Services
npm install phala
Secure. Confidential. Verifiable.
A command-line tool for managing Trusted Execution Environment (TEE) deployments on Phala Cloud, from local development to cloud deployment.
___
👥 Community & Support
- Dstack-TEE: Dstack
- Bun for runtime and package management
- TypeScript for type safety
- Commander.js for CLI interface
- Zod for runtime validation
1. Install Prerequisites:
``bash`
# Install Bun
curl -fsSL https://bun.sh/install | bash
# Verify Docker is installed
docker --version
2. Install TEE Cloud CLI:
Install via npm or use npx/bunx
`bash`
# Install the CLI globally
npm install -g phala
> NOTE
>
> You can use npx or bunx to call the phala command`
>
> bash`
> # Use npx/bunx
>
> npx phala help
> bunx phala help
> `
bash`
# Phala CLI help menu
npx phala help
3. Sign Up and Get API Key:
To deploy applications to Phala Cloud, you'll need an API key:
- Visit Phala Cloud to log into your Phala Cloud account. If you do not have an account, registe here.
- After logging in, navigate to the "API Keys" section in your profile
- Create a new API key with an appropriate name (e.g., "CLI Access")
- Copy the generated API key - you'll need it for authentication
- You can verify your API key using:
`bash`
phala auth login [your-phala-cloud-api-key]
phala auth status
4. Deploy Your First Confidential App:
Clone the Dstack Examples repo and cd into the webshell directory
`bash`
git clone https://github.com/Dstack-TEE/dstack-examples.git && cd dstack-examples/webshell
`
bash`
# Deploy the webshell Dstack example
phala cvms create
Provide a name and select from the drop down of examples
`bash
# ? Enter a name for the CVM: webshell
# ℹ Detected docker compose file: ./docker-compose.yml
# ? Enter the path to your Docker Compose file:(docker-compose.yml)
# ✔ Enter number of vCPUs (default: 1): 1
# ✔ Enter memory in MB (default: 2048): 2048
# ✔ Enter disk size in GB (default: 20): 20
# ⟳ Fetching available TEEPods... ✓
# ⟳ Getting public key from CVM... ✓
# ⟳ Encrypting environment variables... ✓
# ⟳ Creating CVM... ✓
# ✓ CVM created successfully
# ℹ CVM ID: 2755
# ℹ Name: webshell
# ℹ Status: creating
# ℹ App ID: e15c1a29a9dfb522da528464a8d5ce40ac28039f
# ℹ App URL:
# ℹ
# ℹ Your CVM is being created. You can check its status with:
# ℹ phala cvms status e15c1a29a9dfb522da528464a8d5ce40ac28039f
`
Now interact with your application in Phala Cloud by going to the url on port 7681 (Example of what a url at port 7681 would look like https://e15c1a29a9dfb522da528464a8d5ce40ac28039f-7681.dstack-prod5.phala.network)
5. Check the CVM's Attestation:
`bash
phala cvms attestation
# ℹ No CVM specified, fetching available CVMs...
# ⟳ Fetching available CVMs... ✓
# ✔ Select a CVM: testing (88721d1685bcd57166a8cbe957cd16f733b3da34) - Status: running
# ℹ Fetching attestation information for CVM 88721d1685bcd57166a8cbe957cd16f733b3da34...
# ⟳ Fetching attestation information... ✓
# ✓ Attestation Summary:
# or list the app-id
phala cvms attestation 88721d1685bcd57166a8cbe957cd16f733b3da34
`
Develop and test your application locally with the built-in TEE simulator:
`bashStart the TEE simulator
phala simulator start
$3
Deploy your application to Phala's decentralized TEE Cloud:
`bash
Set your Phala Cloud API key
phala auth loginLogin to Docker and Push your image to Docker Hub
phala docker login
phala docker build --image my-tee-app --tag v1.0.0
phala docker push --image my-tee-app --tag v1.0.0Deploy to Phala Cloud
phala cvms create --name my-tee-app --compose ./docker-compose.yml --env-file ./.envAccess your app via the provided URL
`💼 Real-World Use Cases for Confidential Computing
$3
- Private Trading Algorithms: Execute proprietary trading strategies without revealing algorithms
- Secure Multi-Party Computation: Perform financial calculations across organizations without exposing sensitive data
- Compliant Data Processing: Process regulated financial data with provable security guarantees$3
- Medical Research: Analyze sensitive patient data while preserving privacy
- Drug Discovery: Collaborate on pharmaceutical research without exposing intellectual property
- Health Record Processing: Process electronic health records with HIPAA-compliant confidentiality$3
- Secure Key Management: Generate and store cryptographic keys in hardware-protected environments
- Threat Intelligence Sharing: Share cyber threat data across organizations without exposing sensitive details
- Password Verification: Perform credential validation without exposing password databases$3
- Confidential Analytics: Process sensitive business data without exposure to cloud providers
- IP Protection: Run proprietary algorithms and software while preventing reverse engineering
- Secure Supply Chain: Validate and process sensitive supply chain data across multiple organizations$3
- Private Smart Contracts: Execute contracts with confidential logic and data
- Decentralized Identity: Process identity verification without exposing personal information
- Trustless Oracles: Provide verified external data to blockchain applications🧩 Project Structure
The Phala Cloud CLI is organized around core workflows:
1. Authentication: Connect to your Phala Cloud account
2. TEEPod Info: Fetch information about TEEPods (TEEPods are where your docker apps deploy to)
3. Docker Management: Build and manage Docker images for TEE
4. TEE Simulation: Local development environment
5. Cloud Deployment: Deploy to production and manage TEE Cloud deployments
📚 Command Reference
The Phala Cloud CLI provides a comprehensive set of commands for managing your TEE deployments. Below is a detailed reference for each command category.
$3
Commands for managing authentication with the Phala Cloud API.
#### Login
`bash
phala auth login [options]
`Set the API key for authentication with Phala Cloud. The API key is stored with encryption for enhanced security.
Options:
-
[api-key]: Phala Cloud API key to setExample:
`bash
phala auth login [your-phala-cloud-api-key]
`#### Logout
`bash
phala auth logout
`Remove the stored API key.
Example:
`bash
phala auth logout
`#### Status
`bash
phala status [options]
`Check your authentication status with Phala Cloud. Displays user information including API endpoint, username, and current workspace.
> Note:
phala auth status is still available for backward compatibility, but it's recommended to use phala status instead.Options:
-
-j, --json: Output in JSON format
- -d, --debug: Enable debug outputExample:
`bash
phala status
phala status --json
`#### Environment Variable Override
You can override the stored API key using the
PHALA_CLOUD_API_KEY environment variable. This is useful for CI/CD workflows or testing with different accounts.Example:
`bash
Temporarily use a different API key
PHALA_CLOUD_API_KEY="phak_your_api_key_here" phala cvms listIn CI/CD pipelines
export PHALA_CLOUD_API_KEY="phak_your_api_key_here"
phala deploy --name my-app
`You can also override the API endpoint using the
PHALA_CLOUD_API_PREFIX environment variable.Example:
`bash
PHALA_CLOUD_API_PREFIX="https://cloud-api.phala.ai" phala cvms list
`#### JSON Output Mode
All commands support the
--json flag for machine-readable output, useful for automation and CI/CD pipelines.Example:
`bash
Get CVM list as JSON
phala cvms list --jsonParse with jq
phala status --json | jq '.username'
`$3
Commands for managing Docker images for TEE deployments.
#### Docker Login
`bash
phala docker login [options]
`Login to Docker Hub to enable pushing and pulling images.
Options:
-
-u, --username : Docker Hub username (if not provided, you will be prompted)
- -p, --password : Docker Hub password (if not provided, you will be prompted)
- -r, --registry : Docker registry URL (optional, defaults to Docker Hub)Example:
`bash
phala docker login --username your-dockerhub-username
`#### Build Docker Image
`bash
phala docker build [options]
`Build a Docker image for your TEE application.
Options:
-
-i, --image : Image name (required)
- -t, --tag : Image tag (required)
- -f, --file : Path to Dockerfile (defaults to 'Dockerfile')Example:
`bash
phala docker build --image my-tee-app --tag v1.0.0 --file ./Dockerfile
`#### Push Docker Image
`bash
phala docker push [options]
`Push a Docker image to Docker Hub.
Options:
-
-i, --image : Image name (required)
- -t, --tag : Image tag (required)Example:
`bash
phala docker push --image my-tee-app --tag v1.0.0
`#### Build Docker Compose File
`bash
phala docker generate [options]
`Build a Docker Compose file for your TEE application.
Options:
- -i, --image Docker image name to use in the compose file
- -t, --tag Docker image tag to use in the compose file
- -e, --env-file Path to environment variables file
- -o, --output
Example:
`bash
phala docker generate --image my-tee-app --tag v1.0.0 --env-file ./.env
`$3
Commands for managing the local TEE simulator for development and testing. When run without subcommands, shows the current status of the simulator.
#### Check Status
`bash
phala simulator
`Shows the current status of the TEE simulator, including the process ID and endpoint information if running.
#### Start Simulator
`bash
phala simulator start [options]
`Start the TEE simulator locally for development and testing.
Options:
-
-p, --port : Port to bind the simulator to (default: 8000)
- -v, --verbose: Enable verbose outputExamples:
`bash
Start with default options
phala simulator startStart with verbose output
phala simulator start --verbose
`#### Stop Simulator
`bash
phala simulator stop
`Stop the running TEE simulator.
Example:
`bash
phala simulator stop
`#### Environment Variables
When the simulator is running, you'll need to set these environment variables to use it:
`bash
export DSTACK_SIMULATOR_ENDPOINT=/path/to/dstack.sock
export TAPPD_SIMULATOR_ENDPOINT=/path/to/tappd.sock
`These variables will be automatically displayed when you run
phala simulator while the simulator is running.$3
Commands for managing Cloud Virtual Machines (CVMs) on Phala Cloud.
#### List CVMs
List all your CVMs:
`bash
phala cvms list
`#### Manage TEE Nodes
List all available worker nodes to find TEEPod IDs for replication. You can use any of these commands to list nodes:
`bash
List all available nodes (recommended)
phala nodesAlternative ways to list nodes
phala nodes list
phala nodes ls
`This will show you all available TEEPod nodes along with their IDs, which you can use with the
replicate command's --teepod-id option. The output includes node details such as ID, name, region, FMSPC, device ID, and available images.#### Get CVM Details
`bash
phala cvms get [options]
`Get detailed information about a specific CVM.
Arguments:
-
app-id: App ID of the CVMOptions:
-
-j, --json: Output in JSON formatExample:
`bash
phala cvms get app_123456
`#### Deploy (Simplified)
`bash
phala deploy [options]
`Deploy a new CVM or update an existing one. Creates a new CVM by default. If
--cvm-id is provided or a CVM ID is configured in phala.toml, updates the existing CVM instead.Key Features:
- Auto Resource Matching: Backend automatically finds the best available node based on your requirements
- All Parameters Optional: Specify only what you need; the system handles the rest
- Structured Error Messages: Clear error codes (ERR-xxxx) with actionable suggestions
- On-chain KMS Support: Built-in support for decentralized key management
Options:
-
-n, --name : Name of the CVM (auto-generated from folder name if not provided)
- -c, --compose : Path to Docker Compose file (default: docker-compose.yml)
- -t, --instance-type : Instance type (e.g., tdx.small, tdx.medium, tdx.large) - optional, auto-selected if not specified
- -r, --region : Preferred region (e.g., us-west, eu-central) - optional, auto-selected if not specified
- --vcpu : Number of vCPUs - optional, auto-matched if not specified
- --memory : Memory with unit (e.g., 2G, 1024MB) - optional, auto-matched if not specified
- --disk-size : Disk size with unit (e.g., 50G, 100GB) - optional, auto-matched if not specified
- --image : OS image version - optional, auto-selected if not specified
- --node-id : Specific node ID - optional, auto-selected if not specified
- -e, --env-file : Path to environment variables file
- -i, --interactive: Enable interactive mode for required parameters
- --kms-id : KMS ID for on-chain key management
- --private-key : Private key for on-chain KMS deployment
- --rpc-url : RPC URL for blockchain interaction
- --uuid : UUID of existing CVM to upgrade
- --wait: Wait for deployment/update to complete before returning
- -j, --json: Output in JSON format
- -d, --debug: Enable debug loggingExamples:
`bash
--- New Deployment ---
Simplest - auto-select everything
phala deploySpecify instance type and region
phala deploy --instance-type tdx.medium --region us-westWith environment file
phala deploy -e .envWith on-chain KMS
phala deploy --kms-id ethereum --private-key --rpc-url Interactive mode for guided setup
phala deploy --interactive--- Update Existing CVM ---
Update by CVM ID (app_id, UUID, or name)
phala deploy --cvm-id app_abc123Update with new compose file and environment variables
phala deploy --cvm-id my-app --compose ./new-docker-compose.yml -e .envUpdate and wait for completion
phala deploy --cvm-id app_abc123 --waitIf phala.toml has cvm_id configured, just run deploy to update
phala deploy
`Error Handling:
The deploy command provides structured error messages with unique error codes for easy troubleshooting:
`
Error [ERR-1003]: The selected node does not have enough CPU capacityDetails:
- Need 4 CPUs, but only 2 are available
- node_id: 6
Suggestions:
- Choose a smaller instance type
- Reduce the number of CPUs requested
- Remove the --node-id flag to search all available nodes
Need help? Contact support: https://cloud.phala.com/contact
Reference error code: ERR-1003
`Common error codes:
-
ERR-1001: Instance type not found
- ERR-1002: No available resources match requirements
- ERR-1003: Insufficient CPU capacity
- ERR-1004: Insufficient memory
- ERR-2003: OS image not available
- ERR-2005: Node not accessibleFor a complete list of error codes, refer to the error code documentation.
#### Create CVM
`bash
phala cvms create [options]
`Create a new CVM on Phala Cloud.
Options:
-
-n, --name : Name of the CVM (required)
- -c, --compose : Path to Docker Compose file (required)
- --vcpu : Number of vCPUs (default: 1)
- --memory : Memory in MB (default: 2048)
- --disk-size : Disk size in GB (default: 20)
- --teepod-id : TEEPod ID to launch the CVM to (default: 3)
- --image : Version of dstack image to use (i.e. dstack-0.3.5)
- -e, --env-file : Environment variables in the form of KEY=VALUE
- --skip-env: Path to environment file (default: false)
- --debug: Enable debug modeExample:
`bash
phala cvms create --name my-tee-app --compose ./docker-compose.yml --vcpu 2 --memory 4096 --diskSize 60 --teepod-id 3 --image dstack-dev-0.3.5 --env-file ./.env
`##### Using a Private Docker Registry
You can deploy images from a private Docker registry by setting the appropriate environment variables. Check the docs for more information.
##### 🔐 DockerHub:
Set these variables:
-
DSTACK_DOCKER_USERNAME – Your DockerHub username (required)
- DSTACK_DOCKER_PASSWORD – Your DockerHub password or personal access token (required)
- DSTACK_DOCKER_REGISTRY – Registry URL (optional, defaults to DockerHub)##### 🔐 AWS ECR:
Set these variables:
-
DSTACK_AWS_ACCESS_KEY_ID – AWS access key (required)
- DSTACK_AWS_SECRET_ACCESS_KEY – AWS secret key (required)
- DSTACK_AWS_REGION – AWS region of the ECR (required)
- DSTACK_AWS_ECR_REGISTRY – Full ECR registry URL (required)Once set, the CLI will automatically authenticate and pull your private image securely.
#### Upgrade CVM
`bash
phala cvms upgrade [options]
`Upgrade a CVM to a new version.
Arguments:
-
app-id: App ID of the CVM to upgradeOptions:
-
-c, --compose : Path to new Docker Compose file
- --env-file : Path to environment file
- --debug: Enable debug modeExample:
`bash
phala cvms upgrade app_123456 --compose ./new-docker-compose.yml --env-file ./.env
`#### Start CVM
`bash
phala cvms start [app-id]
`Start a stopped CVM.
Arguments:
-
app-id: App ID of the CVM to startExample:
`bash
phala cvms start e15c1a29a9dfb522da528464a8d5ce40ac28039f
`#### Stop CVM
`bash
phala cvms stop [app-id]
`Stop a running CVM.
Arguments:
-
app-id: App ID of the CVM to stopExample:
`bash
phala cvms stop e15c1a29a9dfb522da528464a8d5ce40ac28039f
`#### Restart CVM
`bash
phala cvms restart [app-id]
`Restart a CVM.
Arguments:
-
app-id: App ID of the CVM to restartExample:
`bash
phala cvms restart e15c1a29a9dfb522da528464a8d5ce40ac28039f
`#### Replicate App
`bash
phala cvms replicate [options]
`Create a replica of an existing App using cvm-uuid. Before replicating, you can use
phala nodes to find available TEEPod IDs.Basic Usage:
`bash
phala cvms replicate
`Options:
-
--teepod-id : TEEPod ID to use for the replica (use phala nodes to find available TEEPod IDs)
- -e, --env-file : Path to environment file for the replica (will be encrypted with the original CVM's public key)Example Workflow:
`bash
List available nodes to find a teepod-id
phala nodesCreate a replica using a specific teepod-id
phala cvms replicate --teepod-id 123With environment variables
phala cvms replicate -e .env
`Example:
`bash
Basic usage
phala cvms replicate e15c1a29a9dfb522da528464a8d5ce40ac28039fSpecify a different TEEPod
phala cvms replicate e15c1a29a9dfb522da528464a8d5ce40ac28039f --teepod-id 123Use a different environment file
phala cvms replicate e15c1a29a9dfb522da528464a8d5ce40ac28039f -e .env.new
`#### Delete CVM
`bash
phala cvms delete [options]
`Delete a CVM.
Arguments:
-
app-id: App ID of the CVM to deleteOptions:
-
-f, --force: Skip confirmation promptExample:
`bash
phala cvms delete e15c1a29a9dfb522da528464a8d5ce40ac28039f
phala cvms delete --force e15c1a29a9dfb522da528464a8d5ce40ac28039f
`📋 Sample Applications
Explore these example applications to understand different use cases for TEE deployment:
- Timelock Encryption: Encrypt messages that can only be decrypted after a specified time
- Light Client: A lightweight blockchain client implementation
- SSH Over TEE Proxy: Secure SSH tunneling through a TEE
- Web Shell: Browser-based secure terminal
- Custom Domain: Deploy with your own domain name
- Private Docker Image: Deploy using private Docker registries
🛠️ Advanced Features
$3
> This feature is still being developed. Best to build your own docker-compose file for now.
(WIP) Choose from docker compose file for your application:
`bash
phala docker generate --image my-app --tag v1.0.0 --env
`$3
Resize specific resources for your existing CVM:
`bash
phala cvms resize e15c1a29a9dfb522da528464a8d5ce40ac28039f --name resource-intensive-app --compose ./compose.yml \
--vcpu 4 --memory 8192 --disk-size 50 -r true -y
`$3
`bash
Using env file
phala cvms create --name env-app --compose ./compose.yml --env-file ./.env
`
🔒 Security
The TEE Cloud CLI employs several security measures:
1. Encrypted Credentials: API keys and Docker credentials are stored with encryption using a machine-specific key
2. Restricted Permissions: All credential files are stored with 0600 permissions (user-only access)
3. No Validation Storage: API keys are not validated during login, preventing unnecessary transmission
4. Local Storage: All credentials are stored locally in the
~/.phala-cloud/ directory🔍 Troubleshooting
Common issues and solutions:
1. Docker Build Fails
- Verify Docker daemon is running
- Check Dockerfile path
- Ensure proper permissions
2. Simulator Issues
- Check if port 8090 is available
- Verify Docker permissions
3. Cloud Deployment Fails
- Validate API key
- Confirm image exists on Docker Hub
- Check environment variables
For detailed help:
`bash
phala --help
phala --help
`📝 License
Apache 2.0
🤝 Contributing
To contribute or run in development mode:
`bash
bun run src/index.ts
``