Phala Cloud CLI

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

Phala Network Discord | GitHub Issues | Phala Documentation

Usage

Dstack-TEE: Dstack
Bun for runtime and package management
TypeScript for type safety
Commander.js for CLI interface
Zod for runtime validation

🚀 Quick Start (5 Minutes)

Install Prerequisites:

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Verify Docker is installed
docker --version

Install TEE Cloud CLI:

Install via npm or use npx/bunx

# Install the CLI globally
npm install -g phala

NOTE

You can use npx or bunx to call the phala command
# Use npx/bunx

npx phala help
bunx phala help

# Phala CLI help menu
npx phala help

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, register with this link with PROMO_CODE or run npx phala free in the terminal.
- 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:
```
phala auth login [your-phala-cloud-api-key]
phala auth status
```

Deploy Your First Confidential App: Clone the Dstack Examples repo and cd into the webshell directory

git clone https://github.com/Dstack-TEE/dstack-examples.git && cd dstack-examples/webshell

# Deploy the webshell Dstack example
phala cvms create

Provide a name and select from the drop down of examples

# ? 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: <https://cloud.phala.network/dashboard/cvms/app_e15c1a29a9dfb522da528464a8d5ce40ac28039f>
#    ℹ
#    ℹ 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)

Check the CVM's Attestation:

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

🏗️ Development Workflow

1️⃣ Local Development

Develop and test your application locally with the built-in TEE simulator:

# Start the TEE simulator
phala simulator start

# Build your Docker image
phala docker build --image my-tee-app --tag v1.0.0

# Create an environment file
echo "API_KEY=test-key" > .env
echo "DEBUG=true" >> .env

2️⃣ Cloud Deployment

Deploy your application to Phala's decentralized TEE Cloud:

# Set your Phala Cloud API key
phala auth login

# Login 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.0

# Deploy to Phala Cloud
phala cvms create --name my-tee-app --compose ./docker-compose.yml --env-file ./.env

# Access your app via the provided URL

💼 Real-World Use Cases for Confidential Computing

🏦 Financial Services

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

🏥 Healthcare

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

🔐 Cybersecurity

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

🏢 Enterprise Applications

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

🌐 Web3 and Blockchain

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:

Authentication: Connect to your Phala Cloud account
TEEPod Info: Fetch information about TEEPods (TEEPods are where your docker apps deploy to)
Docker Management: Build and manage Docker images for TEE
TEE Simulation: Local development environment
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.

Authentication Commands

Commands for managing authentication with the Phala Cloud API.

Login

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 set

Example:

phala auth login [your-phala-cloud-api-key]

Logout

phala auth logout

Remove the stored API key.

Example:

phala auth logout

Status

phala auth status [options]

Check your authentication status with Phala Cloud. Displays user information in a table format.

Options:

-j, --json: Output in JSON format

Example:

phala auth status
phala auth status --json

Docker Management Commands

Commands for managing Docker images for TEE deployments.

Docker Login

phala docker login [options]

Login to Docker Hub to enable pushing and pulling images.

Options:

-u, --username <username>: Docker Hub username (if not provided, you will be prompted)
-p, --password <password>: Docker Hub password (if not provided, you will be prompted)
-r, --registry <registry>: Docker registry URL (optional, defaults to Docker Hub)

Example:

phala docker login --username your-dockerhub-username

Build Docker Image

phala docker build [options]

Build a Docker image for your TEE application.

Options:

-i, --image <image>: Image name (required)
-t, --tag <tag>: Image tag (required)
-f, --file <file>: Path to Dockerfile (defaults to 'Dockerfile')

Example:

phala docker build --image my-tee-app --tag v1.0.0 --file ./Dockerfile

Push Docker Image

phala docker push [options]

Push a Docker image to Docker Hub.

Options:

-i, --image <image>: Image name (required)
-t, --tag <tag>: Image tag (required)

Example:

phala docker push --image my-tee-app --tag v1.0.0

Build Docker Compose File

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 Output path for generated docker-compose.yml
--template Template to use for the generated docker-compose.yml
--manual Skip automatic image detection and enter image/tag manually
-h, --help display help for command

Example:

phala docker generate --image my-tee-app --tag v1.0.0 --env-file ./.env

TEE Simulator Commands

Commands for managing the local TEE simulator for development and testing.

Start Simulator

phala simulator start [options]

Start the TEE simulator locally for development and testing.

Options:

-i, --image <image>: Simulator image (defaults to 'phalanetwork/tappd-simulator:latest')

Example:

phala simulator start

Stop Simulator

phala simulator stop

Stop the running TEE simulator.

Example:

phala simulator stop

Cloud Virtual Machine (CVM) Commands

Commands for managing Cloud Virtual Machines (CVMs) on Phala Cloud.

List CVMs

phala cvms list|ls [options]

List all CVMs associated with your account.

Options:

-j, --json: Output in JSON format

Example:

phala cvms list

Get CVM Details

phala cvms get [options] <app-id>

Get detailed information about a specific CVM.

Arguments:

app-id: App ID of the CVM

Options:

-j, --json: Output in JSON format

Example:

phala cvms get app_123456

Create CVM

phala cvms create [options]

Create a new CVM on Phala Cloud.

Options:

-n, --name <name>: Name of the CVM (required)
-c, --compose <compose>: Path to Docker Compose file (required)
--vcpu <vcpu>: Number of vCPUs (default: 1)
--memory <memory>: Memory in MB (default: 2048)
--disk-size <diskSize>: Disk size in GB (default: 20)
--teepod-id <teepodId>: TEEPod ID to launch the CVM to (default: 3)
--image <image>: Version of dstack image to use (i.e. dstack-0.3.5)
-e, --env-file <envFile>: Environment variables in the form of KEY=VALUE
--skip-env: Path to environment file (default: false)
--debug: Enable debug mode

Example:

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

Upgrade CVM

phala cvms upgrade [options] <app-id>

Upgrade a CVM to a new version.

Arguments:

app-id: App ID of the CVM to upgrade

Options:

-c, --compose <compose>: Path to new Docker Compose file
--env-file <envFile>: Path to environment file
--debug: Enable debug mode

Example:

phala cvms upgrade app_123456 --compose ./new-docker-compose.yml --env-file ./.env

Start CVM

phala cvms start [app-id]

Start a stopped CVM.

Arguments:

app-id: App ID of the CVM to start

Example:

phala cvms start e15c1a29a9dfb522da528464a8d5ce40ac28039f

Stop CVM

phala cvms stop [app-id]

Stop a running CVM.

Arguments:

app-id: App ID of the CVM to stop

Example:

phala cvms stop e15c1a29a9dfb522da528464a8d5ce40ac28039f

Restart CVM

phala cvms restart [app-id]

Restart a CVM.

Arguments:

app-id: App ID of the CVM to restart

Example:

phala cvms restart e15c1a29a9dfb522da528464a8d5ce40ac28039f

Delete CVM

phala cvms delete [options] <app-id>

Delete a CVM.

Arguments:

app-id: App ID of the CVM to delete

Options:

-f, --force: Skip confirmation prompt

Example:

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

Docker Compose Templates

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:

phala docker generate --image my-app --tag v1.0.0 --env

Customizing Resource Allocation

Resize specific resources for your existing CVM:

phala cvms resize e15c1a29a9dfb522da528464a8d5ce40ac28039f --name resource-intensive-app --compose ./compose.yml \
  --vcpu 4 --memory 8192 --disk-size 50 -r true -y

Environment Variables Management

# Using env file
phala cvms create --name env-app --compose ./compose.yml --env-file ./.env

🔒 Security

The TEE Cloud CLI employs several security measures:

Encrypted Credentials: API keys and Docker credentials are stored with encryption using a machine-specific key
Restricted Permissions: All credential files are stored with 0600 permissions (user-only access)
No Validation Storage: API keys are not validated during login, preventing unnecessary transmission
Local Storage: All credentials are stored locally in the ~/.phala-cloud/ directory

🔍 Troubleshooting

Common issues and solutions:

Docker Build Fails
- Verify Docker daemon is running
- Check Dockerfile path
- Ensure proper permissions
Simulator Issues
- Check if port 8090 is available
- Verify Docker permissions
Cloud Deployment Fails
- Validate API key
- Confirm image exists on Docker Hub
- Check environment variables

For detailed help:

phala --help
phala <command> --help

📝 License

Apache 2.0

🤝 Contributing

To contribute or run in development mode:

bun run src/index.ts

Name		Name	Last commit message	Last commit date
Latest commit History 57 Commits
.github/workflows		.github/workflows
examples @ 9f39acf		examples @ 9f39acf
src		src
test		test
.gitignore		.gitignore
.gitmodules		.gitmodules
COMMANDS.md		COMMANDS.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
bun.lockb		bun.lockb
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

License

Phala-Network/phala-cloud-cli

Folders and files

Latest commit

History

Repository files navigation

Phala Cloud CLI

Usage

🚀 Quick Start (5 Minutes)

🏗️ Development Workflow

1️⃣ Local Development

2️⃣ Cloud Deployment

💼 Real-World Use Cases for Confidential Computing

🏦 Financial Services

🏥 Healthcare

🔐 Cybersecurity

🏢 Enterprise Applications

🌐 Web3 and Blockchain

🧩 Project Structure

📚 Command Reference

Authentication Commands

Login

Logout

Status

Docker Management Commands

Docker Login

Build Docker Image

Push Docker Image

Build Docker Compose File

TEE Simulator Commands

Start Simulator

Stop Simulator

Cloud Virtual Machine (CVM) Commands

List CVMs

Get CVM Details

Create CVM

Upgrade CVM

Start CVM

Stop CVM

Restart CVM

Delete CVM

📋 Sample Applications

🛠️ Advanced Features

Docker Compose Templates

Customizing Resource Allocation

Environment Variables Management

🔒 Security

🔍 Troubleshooting

📝 License

🤝 Contributing

About

Resources

License

Stars

Watchers

Forks

Releases 6

Packages 0

Languages

Packages