CLI Overview

Deploy and manage CVMs from your terminal

The Phala Cloud CLI (phala) is a command-line tool for deploying and managing Confidential Virtual Machines (CVMs) on Phala Cloud. It is also available as the pha alias.

Install

npm install -g phala

Or run without installing: npx phala / bunx phala

Get Started

Follow the Deploy Your First CVM tutorial to deploy a Jupyter notebook and test TEE functions in under 10 minutes.

API Versioning

The CLI communicates with the Phala Cloud API using header-based versioning. The current default API version is 2026-06-23.

The CLI sends an X-Phala-Version header with every request. This determines the response format returned by the server. See the JS SDK API Versioning page for details on version differences.

Version	Status
2026-06-23	Default
2026-05-22	Supported
2026-01-21	Supported
2025-10-28	Legacy

You can override the API version with the --api-version global flag (added in v1.1.12):

phala apps --api-version 2025-10-28

Authentication

Command	Description
login	Authenticate with Phala Cloud
logout	Remove stored API key
status	Check authentication status
whoami	Print the current user
profiles	List auth profiles
switch	Switch auth profiles

Deployment

Command	Description
deploy	Deploy new CVM or update existing one
instance-types	List available instance types

App Management

Command	Description
apps	List deployed CVMs
cvms	Manage CVMs (start, stop, restart, delete, resize, …)
link	Link a local directory to a CVM
nodes	List TEE worker nodes
ssh-keys	Manage SSH keys (list, add, remove, import from GitHub)

CVM Operations

Command	Description
logs	Fetch logs from a CVM (container, serial, stdout/stderr)
ps	List containers of a CVM
ssh	Connect to a CVM via SSH
cp	Copy files to/from a CVM via SCP
runtime-config	Show CVM runtime configuration

Advanced

Command	Description
allow-devices	Manage an app contract’s device allowlist
api	Make authenticated API requests
keccak256sum	Compute or verify Keccak-256 checksums
kms	List KMS contracts and inspect their nodes
self	CLI self-management (update)
simulator	Local TEE simulator for development
completion	Generate shell completion scripts

Deprecated

These commands remain available for compatibility but have newer replacements.

Command	Use instead
auth	login, logout, status
config	Profile-based credentials (~/.phala-cloud/credentials.json)
cvms upgrade	deploy --cvm-id <id>
cvms logs	logs
cvms serial-logs	logs --serial

Deprecated deploy options:

Option	Use instead
--vcpu, --memory	--instance-type
--env-file	-e
--kms-id, --uuid	--custom-app-id

Profiles & Credentials

The CLI supports multiple authentication profiles stored in ~/.phala-cloud/credentials.json.

Each profile stores:

Field	Description
token	API key
api_prefix	API base URL
workspace	Linked workspace (name + slug)
user	Linked user (username + email)
updated_at	Last update timestamp

Use profiles to list profiles and switch to change the active profile.

Environment Variables

Variable	Description
PHALA_CLOUD_API_KEY	Override the stored API key
PHALA_CLOUD_API_PREFIX	Override the API base URL
PHALA_CLOUD_DIR	Override the credentials directory (default: ~/.phala-cloud)
PHALA_UPDATE_CHANNEL	Release channel for self update (e.g., latest, beta)

Configuration

Credentials are stored in ~/.phala-cloud/credentials.json (schema version 1, supports multiple profiles).

Project-level configuration is in phala.toml in the working directory. Supported fields:

Field	Type	Description
id / uuid / app_id / instance_id / name	string	CVM identifier (any format)
profile	string	Auth profile to use for this project
gateway_domain	string	Custom gateway domain
gateway_port	number	Custom gateway port
compose_file	string	Path to Docker Compose file
env_file	string	Path to .env file
public_logs	boolean	Make container logs public
public_sysinfo	boolean	Make system info public
listed	boolean	List CVM in the public directory

Example phala.toml:

id = "cvm-abc123"
profile = "production"
compose_file = "docker-compose.yml"
env_file = ".env"
public_logs = true

Global Flags

Flag	Description
--json	Output in JSON format for programmatic use
--api-token <token>	Override the stored API key for this command
--api-version <version>	Override the API version, including 2026-06-23, 2026-05-22, 2026-01-21, and 2025-10-28
--timeout <seconds>	Set the API request timeout in seconds; the default is 60

Related

• Cloud JS SDK — programmatic access via JavaScript/TypeScript
• Cloud API Reference — full REST API docs
• Local Development — local TEE simulator
• CI/CD Pipeline — GitHub Actions automation