Phala Network Phala Cloud Phala CLI

Phala Cloud CLI

phala (npm) — deploy and manage TEE applications (CVMs) on Phala Cloud.

Operations

Determine what the user wants, then follow the matching procedure:

First Deploy

Step 1: Authenticate

phala login                   # opens browser (device flow)

Headless environment? Use phala login --no-open (prints URL) or phala login phak_xxx (direct key).

Step 2: Deploy

phala deploy -n my-app -c docker-compose.yml -e .env

The compose file must use publicly pullable images, or set DSTACK_DOCKER_USERNAME / DSTACK_DOCKER_PASSWORD in the env file for private registries.

Instance type is auto-selected. Override with -t tdx.small, -t tdx.medium, etc. Check available types: phala instance-types.

Step 3: Link the project

phala link
git add phala.toml            # safe to commit — no secrets

This creates phala.toml binding the directory to the CVM. From now on, deploy, logs, ssh, cp, ps all work without specifying a CVM ID. Everyone on the team gets the same binding.

Step 4: Verify

phala ps                      # containers running?
phala logs -f                 # app output

If containers aren't running, go to Debug a CVM.

Update Existing CVM

With phala.toml in the directory (from phala link):

phala deploy                  # updates the linked CVM

Without phala.toml:

phala deploy --cvm-id app_abc123

The CLI detects a CVM identifier and switches to update mode automatically. Changed compose file, env vars, or deploy flags are applied.

Debug a CVM

Three log sources, escalate in order:

Procedure

1. Check what's running:

   phala ps
   

   If the container is listed and running, go to step 2. If no containers or container is restarting, skip to step 3.

2. Read container logs:

   phala logs -f                     # stream all
   phala logs my-container           # specific container
   phala logs --since 30m            # last 30 minutes only
   

3. Container not starting? Check serial:

   phala logs --serial --tail 200
   

   Look for: docker-compose errors, image pull failures (manifest unknown, unauthorized), OOM kills.

4. CVM not booting at all?

   phala logs --cvm-stderr
   

Common failures in serial logs

SSH & File Transfer

SSH into CVM

phala ssh                             # interactive shell (uses phala.toml)
phala ssh app_abc123                  # by CVM ID
phala ssh -- ls /app                  # run single command
phala ssh -- -L 8080:localhost:80     # port forwarding

Everything after -- is passed to ssh. -o ProxyCommand is blocked for security.

Copy files

phala cp ./config.yml :~/             # upload to linked CVM (: prefix = phala.toml CVM)
phala cp my-app:~/logs/ ./logs/ -r    # download from named CVM

Path format: local-path, cvm-name:remote-path, or :remote-path (linked CVM from phala.toml).

SSH not working?

phala ssh --dry-run                   # print the actual ssh command
phala ssh --verbose                   # connection details

Common causes:

• CVM not running → phala apps --search my-app to check status
• No SSH key → redeploy with --ssh-pubkey ~/.ssh/id_rsa.pub
• Key mismatch → phala ssh -- -i ~/.ssh/correct_key

CI/CD Setup

export PHALA_CLOUD_API_KEY="phak_..."
phala deploy --name my-app --wait     # --wait blocks until CVM is ready
phala logs --tail 20                  # verify startup

--wait is critical in CI — without it, deploy returns immediately and the CVM may not be ready when subsequent steps run.

With phala.toml committed to the repo, CI just needs PHALA_CLOUD_API_KEY and phala deploy --wait.

Attestation

phala cvms attestation                # human-readable (uses phala.toml)
phala cvms attestation app_abc123     # by CVM ID
phala cvms attestation --json | jq '.quote'   # extract quote for verification

On-chain KMS Deploy

For Ethereum or Base KMS instead of the default Phala KMS:

phala deploy -n my-app -c docker-compose.yml \
  --kms ethereum --private-key 0x... --rpc-url https://eth.merkle.io

phala deploy -n my-app -c docker-compose.yml \
  --kms base --private-key 0x... --rpc-url https://mainnet.base.org

Multiple Workspaces

phala login --profile work            # creates "work" profile
phala login --profile personal        # creates "personal" profile
phala switch work                     # switch active profile
phala profiles                        # list all (active marked with *)
phala whoami                          # verify current user

A phala.toml can also pin a profile: add profile = "work" so commands in that directory always use the right workspace.

CVM Identification

Commands accept CVM identifiers in any format:

• App ID: app_abc123def456
• Instance ID: instance_abc123
• UUID: 91b62ea0-6c64-...
• Name: my-app

With phala.toml present, no identifier needed.

Gotchas

Reference Files

Converted and distributed by TomeVault — claim your Tome and manage your conversions.