phala 1.1.0-beta.2 → 1.1.0-beta.3

package/README.md

@@ -446,6 +446,92 @@ Get detailed information about a specific CVM.
 phala cvms get app_123456
 ```
 
+#### Deploy (Simplified)
+
+```bash
+phala deploy [options]
+```
+
+Create a new CVM with automatic resource matching. This is the recommended command for most users as it simplifies deployment by automatically selecting optimal resources based on availability.
+
+**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>`: Name of the CVM (auto-generated from folder name if not provided)
+- `-c, --compose <compose>`: Path to Docker Compose file (default: docker-compose.yml)
+- `-t, --instance-type <type>`: Instance type (e.g., tdx.small, tdx.medium, tdx.large) - **optional**, auto-selected if not specified
+- `-r, --region <region>`: Preferred region (e.g., us-west, eu-central) - **optional**, auto-selected if not specified
+- `--vcpu <vcpu>`: Number of vCPUs - **optional**, auto-matched if not specified
+- `--memory <memory>`: Memory with unit (e.g., 2G, 1024MB) - **optional**, auto-matched if not specified
+- `--disk-size <diskSize>`: Disk size with unit (e.g., 50G, 100GB) - **optional**, auto-matched if not specified
+- `--image <image>`: OS image version - **optional**, auto-selected if not specified
+- `--node-id <nodeId>`: Specific node ID - **optional**, auto-selected if not specified
+- `-e, --env-file <envFile>`: Path to environment variables file
+- `-i, --interactive`: Enable interactive mode for required parameters
+- `--kms-id <kmsId>`: KMS ID for on-chain key management
+- `--private-key <key>`: Private key for on-chain KMS deployment
+- `--rpc-url <url>`: RPC URL for blockchain interaction
+- `--uuid <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 logging
+
+**Examples:**
+
+```bash
+# Simplest - auto-select everything
+phala deploy
+
+# Specify instance type and region
+phala deploy --instance-type tdx.medium --region us-west
+
+# Manual resource specification
+phala deploy --vcpu 4 --memory 8G --disk-size 100G
+
+# With on-chain KMS
+phala deploy --kms-id ethereum --private-key <key> --rpc-url <url>
+
+# Deploy to specific node (advanced)
+phala deploy --node-id 6
+
+# Interactive mode for guided setup
+phala deploy --interactive
+```
+
+**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 capacity
+
+Details:
+  - 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.network/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 accessible
+
+For a complete list of error codes, refer to the error code documentation.
+
 #### Create CVM
 
 ```bash

package/dist/api/index.d.ts

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { CvmLegacyDetail } from '@phala/cloud';
+export { CvmLegacyDetail as CvmInfoResponse } from '@phala/cloud';
 
 declare const dockerConfigSchema: z.ZodObject<{
     password: z.ZodString;
@@ -104,42 +106,42 @@ declare const postCvmResponseSchema: z.ZodObject<{
         name?: string;
         id?: number;
     }>>;
-    user_id: z.ZodNumber;
+    user_id: z.ZodNullable<z.ZodNumber>;
     app_id: z.ZodString;
     vm_uuid: z.ZodNullable<z.ZodString>;
     instance_id: z.ZodNullable<z.ZodString>;
     app_url: z.ZodNullable<z.ZodString>;
-    base_image: z.ZodString;
+    base_image: z.ZodNullable<z.ZodString>;
     vcpu: z.ZodNumber;
     memory: z.ZodNumber;
     disk_size: z.ZodNumber;
-    manifest_version: z.ZodNumber;
-    version: z.ZodString;
-    runner: z.ZodString;
-    docker_compose_file: z.ZodString;
+    manifest_version: z.ZodNullable<z.ZodNumber>;
+    version: z.ZodNullable<z.ZodString>;
+    runner: z.ZodNullable<z.ZodString>;
+    docker_compose_file: z.ZodNullable<z.ZodString>;
     features: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
     created_at: z.ZodString;
-    encrypted_env_pubkey: z.ZodString;
+    encrypted_env_pubkey: z.ZodNullable<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     status?: string;
     name?: string;
     vcpu?: number;
     memory?: number;
+    id?: number;
+    app_id?: string;
+    instance_id?: string;
     version?: string;
     runner?: string;
     docker_compose_file?: string;
     features?: string[];
     manifest_version?: number;
-    id?: number;
     teepod_id?: number;
     teepod?: {
         name?: string;
         id?: number;
     };
     user_id?: number;
-    app_id?: string;
     vm_uuid?: string;
-    instance_id?: string;
     app_url?: string;
     base_image?: string;
     disk_size?: number;
@@ -150,21 +152,21 @@ declare const postCvmResponseSchema: z.ZodObject<{
     name?: string;
     vcpu?: number;
     memory?: number;
+    id?: number;
+    app_id?: string;
+    instance_id?: string;
     version?: string;
     runner?: string;
     docker_compose_file?: string;
     features?: string[];
     manifest_version?: number;
-    id?: number;
     teepod_id?: number;
     teepod?: {
         name?: string;
         id?: number;
     };
     user_id?: number;
-    app_id?: string;
     vm_uuid?: string;
-    instance_id?: string;
     app_url?: string;
     base_image?: string;
     disk_size?: number;
@@ -198,9 +200,9 @@ declare const getCvmNetworkResponseSchema: z.ZodObject<{
         instance?: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
+    error?: string;
     is_online?: boolean;
     is_public?: boolean;
-    error?: string;
     internal_ip?: string;
     latest_handshake?: string;
     public_urls?: {
@@ -208,9 +210,9 @@ declare const getCvmNetworkResponseSchema: z.ZodObject<{
         instance?: string;
     }[];
 }, {
+    error?: string;
     is_online?: boolean;
     is_public?: boolean;
-    error?: string;
     internal_ip?: string;
     latest_handshake?: string;
     public_urls?: {
@@ -288,42 +290,42 @@ declare const replicateCvmResponseSchema: z.ZodObject<{
         name?: string;
         id?: number;
     }>;
-    user_id: z.ZodNumber;
+    user_id: z.ZodNullable<z.ZodNumber>;
     app_id: z.ZodString;
-    vm_uuid: z.ZodString;
+    vm_uuid: z.ZodNullable<z.ZodString>;
     instance_id: z.ZodNullable<z.ZodString>;
     app_url: z.ZodNullable<z.ZodString>;
-    base_image: z.ZodString;
+    base_image: z.ZodNullable<z.ZodString>;
     vcpu: z.ZodNumber;
     memory: z.ZodNumber;
     disk_size: z.ZodNumber;
-    manifest_version: z.ZodNumber;
+    manifest_version: z.ZodNullable<z.ZodNumber>;
     version: z.ZodNullable<z.ZodString>;
-    runner: z.ZodString;
-    docker_compose_file: z.ZodString;
+    runner: z.ZodNullable<z.ZodString>;
+    docker_compose_file: z.ZodNullable<z.ZodString>;
     features: z.ZodNullable<z.ZodArray<z.ZodString, "many">>;
     created_at: z.ZodString;
-    encrypted_env_pubkey: z.ZodString;
+    encrypted_env_pubkey: z.ZodNullable<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     status?: string;
     name?: string;
     vcpu?: number;
     memory?: number;
+    id?: number;
+    app_id?: string;
+    instance_id?: string;
     version?: string;
     runner?: string;
     docker_compose_file?: string;
     features?: string[];
     manifest_version?: number;
-    id?: number;
     teepod_id?: number;
     teepod?: {
         name?: string;
         id?: number;
     };
     user_id?: number;
-    app_id?: string;
     vm_uuid?: string;
-    instance_id?: string;
     app_url?: string;
     base_image?: string;
     disk_size?: number;
@@ -334,21 +336,21 @@ declare const replicateCvmResponseSchema: z.ZodObject<{
     name?: string;
     vcpu?: number;
     memory?: number;
+    id?: number;
+    app_id?: string;
+    instance_id?: string;
     version?: string;
     runner?: string;
     docker_compose_file?: string;
     features?: string[];
     manifest_version?: number;
-    id?: number;
     teepod_id?: number;
     teepod?: {
         name?: string;
         id?: number;
     };
     user_id?: number;
-    app_id?: string;
     vm_uuid?: string;
-    instance_id?: string;
     app_url?: string;
     base_image?: string;
     disk_size?: number;
@@ -507,9 +509,9 @@ declare const cvmAttestationResponseSchema: z.ZodObject<{
     }>>;
     compose_file: z.ZodNullable<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    error?: string;
     is_online?: boolean;
     is_public?: boolean;
-    error?: string;
     app_certificates?: {
         version?: string;
         subject?: {
@@ -551,9 +553,9 @@ declare const cvmAttestationResponseSchema: z.ZodObject<{
     };
     compose_file?: string;
 }, {
+    error?: string;
     is_online?: boolean;
     is_public?: boolean;
-    error?: string;
     app_certificates?: {
         version?: string;
         subject?: {
@@ -773,18 +775,7 @@ interface PubkeyResponse {
     app_env_encrypt_pubkey: string;
     app_id_salt: string;
 }
-interface CvmInfoResponse {
-    id: number;
-    name: string;
-    status: string;
-    app_id: string;
-    vcpu: number;
-    memory: number;
-    disk_size: number;
-    base_image: string;
-    encrypted_env_pubkey: string;
-    env_pubkey?: string;
-}
+
 interface UpgradeResponse {
     detail?: string;
     [key: string]: unknown;
@@ -809,15 +800,16 @@ interface CvmComposeConfigResponse {
 /**
  * Check CVM exists for the current user and appId
  * @param appId App ID (with or without app_ prefix)
+ * @param silent If true, don't log success/error messages (useful for JSON output mode)
  * @returns CVM appId string (without app_ prefix) or throws if not found
  */
-declare function checkCvmExists(appId: string): Promise<string>;
+declare function checkCvmExists(appId: string, silent?: boolean): Promise<string>;
 /**
  * Get CVM by App ID using SDK
  * @param appId App ID (with or without app_ prefix)
  * @returns CVM details
  */
-declare function getCvmByAppId(appId: string): Promise<CvmInfoResponse>;
+declare function getCvmByAppId(appId: string): Promise<CvmLegacyDetail>;
 /**
  * Get CVM compose configuration
  */
@@ -926,4 +918,4 @@ declare function upgradeCvm(appId: string, vmConfig: VMConfig): Promise<UpgradeR
  */
 declare function getTeepods(v03x_only?: boolean): Promise<TeepodResponse>;
 
-export { AvailableNodesResponse, CertificateInfo, CertificateNameInfo, ComposeFile, CvmAttestationResponse, CvmComposeConfigResponse, CvmInfoResponse, CvmListResponse, DockerConfig, EncryptedEnvItem, GetCvmNetworkResponse, Image, KmsListItem, PostCvmResponse, PubkeyResponse, ReplicateCvmResponse, ResizeCvmPayload, TCBEventLogEntry, TCBInfo, TEEPod, TeepodResponse, UpgradeResponse, UserInfoResponse, VMConfig, checkCvmExists, composeFileSchema, createCvm, cvmAttestationResponseSchema, deleteCvm, dockerConfigSchema, encryptedEnvItemSchema, getCvmAttestation, getCvmByAppId, getCvmComposeConfig, getCvmNetwork, getCvmNetworkResponseSchema, getPubkeyFromCvm, getTeepods, imageSchema, postCvmResponseSchema, replicateCvm, replicateCvmResponseSchema, resizeCvm, restartCvm, selectCvm, startCvm, stopCvm, teepodSchema, upgradeCvm };
+export { AvailableNodesResponse, CertificateInfo, CertificateNameInfo, ComposeFile, CvmAttestationResponse, CvmComposeConfigResponse, CvmListResponse, DockerConfig, EncryptedEnvItem, GetCvmNetworkResponse, Image, KmsListItem, PostCvmResponse, PubkeyResponse, ReplicateCvmResponse, ResizeCvmPayload, TCBEventLogEntry, TCBInfo, TEEPod, TeepodResponse, UpgradeResponse, UserInfoResponse, VMConfig, checkCvmExists, composeFileSchema, createCvm, cvmAttestationResponseSchema, deleteCvm, dockerConfigSchema, encryptedEnvItemSchema, getCvmAttestation, getCvmByAppId, getCvmComposeConfig, getCvmNetwork, getCvmNetworkResponseSchema, getPubkeyFromCvm, getTeepods, imageSchema, postCvmResponseSchema, replicateCvm, replicateCvmResponseSchema, resizeCvm, restartCvm, selectCvm, startCvm, stopCvm, teepodSchema, upgradeCvm };