> ## 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.

# Installation

<Card title="Need the shared platform overview?" icon="circle-info" href="/fundamentals/v2/overview/what-is-ghostable">
  Use Fundamentals for shared concepts. Use this guide when you specifically need the CLI.
</Card>

<Note>
  On macOS, start with the [Desktop app](/desktop/v1/getting-started/overview) unless you
  explicitly need terminal scripting, automation, or a non-macOS workflow.
</Note>

## Account Creation

Before integrating Ghostable into your workflow, you’ll first need to create a Ghostable account. If
you’re collaborating on projects managed by others, a Ghostable subscription isn’t necessary.

<Card title="Start with a free Ghostable account" icon="user-plus" href="https://ghostable.dev/register">
  Setup takes less than a minute.
</Card>

## Requirements

**System**

* **Node.js 20 LTS** (18+ supported) — macOS, Linux, or Windows.
* No PHP required for standard Ghostable CLI operations.

**Laravel**

* Ghostable supports Laravel applications compatible with **PHP 8.1+** and **Laravel 10.0+**.
* These requirements only apply if you are using Ghostable’s **Laravel-specific deployment
  commands**.
* In all other cases, Ghostable runs fully standalone as a Node-based CLI.

## Installing the Ghostable CLI

You will interact with your Ghostable environments using the
[Ghostable CLI](https://github.com/ghostable-dev/cli). The CLI can be installed globally or on a
per-project basis from npm:

```bash theme={null}
# Per-project
npm install @ghostable/cli@latest

# Global
npm install -g @ghostable/cli@latest
```

Then verify the CLI is on your PATH:

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

<Card title="Vendor verification (checksums + provenance)" icon="shield-check" href="/fundamentals/v2/security-and-operations/supply-chain-verification">
  Validate release checksums, SBOM artifacts, and provenance attestations before rollout.
</Card>

<Note>
  To save keystrokes, you can add a shell alias that maps `ghostable` to `npx ghostable`. This
  allows you to run `ghostable` directly without prefixing every command.
</Note>

***

### Creating an Account

Prefer to handle sign-up from the terminal? Run the CLI registration command and complete the flow
in your browser:

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

The CLI launches Ghostable in your default browser (or prints a one-time link) so you can create an
account or finish SSO. Once registration succeeds, the CLI finalizes your session automatically.

If your email needs verification, the CLI lets you know—verify the address from your inbox, then run
`ghostable login` to continue.

### Logging In

The CLI now authenticates through your browser for a faster, more secure flow. Run:

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

What happens next:

* The CLI opens your default browser (or prints a one-time link if it can’t) and takes you to the
  Ghostable login screen.
* Complete the login or SSO flow in the browser; the CLI will wait and confirm when authentication
  succeeds.
* If the browser flow is unsupported in your environment, the CLI automatically falls back to the
  classic prompts for email, password, and 2FA (when enabled).

### Exploring Commands

Use the global help flag to see every top-level command exposed by the CLI:

```bash theme={null}
$ ghostable --help

Usage: ghostable [options] [command]

Options:
  -V, --version   output the version number
  -h, --help      display help for command

Commands:
  login           Authenticate this CLI session with Ghostable
  register        Register a Ghostable account via browser flow
  init            Link this directory to a Ghostable project
  env             Manage Ghostable environments and related workflows
  var             Manage individual Ghostable environment variable workflows
  device          Manage Ghostable device identities and lifecycle actions
  org             Manage Ghostable organizations and related contexts
  deploy          Deploy Ghostable secrets to managed platforms or CI tokens
  help [command]  display help for command

(Output trimmed—your local build may list additional commands as new features land.)
```

Many of these commands expand into their own menus. Append `--help` after the command to see the
available subcommands and options:

```bash theme={null}
$ ghostable env --help

Usage: ghostable env [options] [command]

Manage Ghostable environments and related workflows

Commands:
  list         Show environments defined in your manifest
  create       Create a new environment from scratch or by duplicating another
  push         Encrypt and push your local .env file to Ghostable
  pull         Download a remote environment into a local .env file
  sync         Replace the remote environment with your local copy
  diff         Compare local vs. remote variables
  validate     Validate env files against your schema
  deploy       Deploy an environment to Forge, Vapor, or Cloud
  history      Inspect environment history
```

Likewise, `ghostable device --help` reveals flows such as `device link`, `device status`, and
`device unlink`. If you already know the exact command, attach `--help` after it to inspect its
flags—for example, `ghostable env push --help`.

## Organizations

When you create a Ghostable account, your first step is to create an organization. Organizations act
as containers for your projects and environments, and you can belong to multiple organizations to
collaborate with different groups or clients.

All projects and environments in Ghostable belong to an organization. You can join other
organizations as a collaborator or create your own to organize work by client or topic.

### Listing Organizations

To view all organizations you belong to:

```bash theme={null}
ghostable org list
```

### Current Organization & Switching Organizations

When working with the Ghostable CLI, you'll often need to know which organization is currently
active. To check your current organization:

```bash theme={null}
ghostable org current
```

To switch to another organization:

```bash theme={null}
ghostable org switch
```

***

## What's Next?

<CardGroup>
  <Card title="Link this repo" icon="terminal" href="/cli/v2/workflows/projects">
    Run `ghostable init` inside your project to link it to an organization and generate the
    manifest.
  </Card>

  <Card title="Link your device" icon="laptop" href="/cli/v2/workflows/devices">
    Use `ghostable device link` so encryption keys live in your OS keychain and pushes succeed.
  </Card>

  <Card title="Prepare deployments" icon="lock" href="/cli/v2/workflows/deploy-tokens">
    Create deployment tokens so CI, Laravel platforms, or container builds can fetch secrets
    securely.
  </Card>
</CardGroup>