> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phala.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={"system"}
npm install -g phala
```

Or run without installing: `npx phala` / `bunx phala`

## Get Started

Follow the [Deploy Your First CVM](/phala-cloud/phala-cloud-cli/start-from-cloud-cli) 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](/phala-cloud/references/cloud-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)*:

```bash theme={"system"}
phala apps --api-version 2025-10-28
```

## Authentication

| Command | Description |
| - | - |
| [`login`](/phala-cloud/phala-cloud-cli/login) | Authenticate with Phala Cloud |
| [`logout`](/phala-cloud/phala-cloud-cli/logout) | Remove stored API key |
| [`status`](/phala-cloud/phala-cloud-cli/status) | Check authentication status |
| [`whoami`](/phala-cloud/phala-cloud-cli/whoami) | Print the current user |
| [`profiles`](/phala-cloud/phala-cloud-cli/profiles) | List auth profiles |
| [`switch`](/phala-cloud/phala-cloud-cli/switch) | Switch auth profiles |

## Deployment

| Command | Description |
| - | - |
| [`deploy`](/phala-cloud/phala-cloud-cli/deploy) | Deploy new CVM or update existing one |
| [`instance-types`](/phala-cloud/phala-cloud-cli/instance-types) | List available instance types |

## App Management

| Command | Description |
| - | - |
| [`apps`](/phala-cloud/phala-cloud-cli/apps) | List deployed CVMs |
| [`cvms`](/phala-cloud/phala-cloud-cli/cvms) | Manage CVMs (start, stop, restart, delete, resize, ...) |
| [`link`](/phala-cloud/phala-cloud-cli/link) | Link a local directory to a CVM |
| [`nodes`](/phala-cloud/phala-cloud-cli/nodes) | List TEE worker nodes |
| [`ssh-keys`](/phala-cloud/phala-cloud-cli/ssh-keys) | Manage SSH keys (list, add, remove, import from GitHub) |

## CVM Operations

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

## Advanced

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

## Deprecated

These commands remain available for compatibility but have newer replacements.

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

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`](/phala-cloud/phala-cloud-cli/profiles) to list profiles and [`switch`](/phala-cloud/phala-cloud-cli/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`:

```toml theme={"system"}
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](/phala-cloud/references/cloud-js-sdk/overview) — programmatic access via JavaScript/TypeScript
* [Cloud API Reference](/phala-cloud/phala-cloud-api/overview) — full REST API docs
* [Local Development](/dstack/local-development) — local TEE simulator
* [CI/CD Pipeline](/phala-cloud/phala-cloud-cli/ci-cd-automation/setup-a-ci-cd-pipeline) — GitHub Actions automation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.