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

# Upgrade Guide

Ghostable **v2** introduces a new, faster CLI built with **TypeScript and npm**, replacing the older
PHP-based Composer package. This guide will help you safely migrate your existing environments to
the new CLI while maintaining all your encrypted data.

***

## 1. Overview

In this version, the CLI is now distributed via npm (`@ghostable/cli`), and supports a
**zero-knowledge architecture** — meaning encryption happens entirely on your machine before any
data reaches Ghostable.\
You’ll still use your same Ghostable account and environments; this process simply re-establishes
your workspace under the new CLI.

***

## 2. Pull Existing Environments (from v1)

Before migrating, download your current `.env` files locally using the legacy PHP CLI.

```bash theme={null}
php vendor/bin/ghostable env:pull
```

Repeat this for each environment.

You’ll now have a set of .env files representing your current data — **keep these safe** while
setting up your new CLI project.

## 3. Install the New CLI

Install the new Ghostable CLI using npm:

```bash theme={null}
npm install -g @ghostable/cli
```

Then confirm the CLI is available:

```bash theme={null}
ghostable --version
```

<Info>
  For full installation details, see the [v2 Installation
  Guide](/cli/v2/getting-started/installation).
</Info>

## 4. Initialize Your Project

Run the new CLI initialization command:

```bash theme={null}
ghostable init
```

Choose **Create a new project**, give it a name, and confirm. This will generate a fresh
**ghostable.yaml** manifest in your repository, configured for the new zero-knowledge encryption
model.

You can safely commit this manifest file to version control.

## 5. Recreate and Push Environments

Next, create new environments and push your previously pulled data.

```bash theme={null}
ghostable env create
ghostable env push
```

Repeat for each environment. Your variables will now be **encrypted locally** and only
**ciphertext** and metadata will be uploaded to Ghostable.

## 6. Clean Up

Finally, log in to the [Ghostable Dashboard](https://ghostable.dev/login) and remove your old (v1)
project to prevent confusion or duplicate configurations. You are then free to remove the v1
composer package.

```bash theme={null}
composer remove ghostable-dev/cli
```