docs / getting-started

> Getting Started

From zero to activated environment in under 5 minutes.

_prerequisites

Ghost-Env works on any Unix-like system. You'll need:

+
curl - For downloading and running the activation script
+
bash or zsh - Your shell (most systems have one)
+
A web browser - For authentication and the dashboard

# Check your system

curl --version && echo "Ready!"

Create Your Account

Head to gh-env.sh/auth and create your account. You'll need:

- A valid email address
- A username (lowercase, alphanumeric)
- A strong password (8+ characters)

Pro tip: Enable two-factor authentication in Settings for extra security.

Create Your First Profile

After logging in, go to your Dashboard and create a new profile. A profile contains:

Environment Variables

Export variables like PATH additions, API keys, or custom settings.

export EDITOR=vim
export PROJECT_ENV=dev

Aliases

Shortcuts for frequently used commands.

alias ll='ls -la'
alias gs='git status'

Functions

Complex shell functions for advanced workflows.

mkcd() {
mkdir -p "$1" && cd "$1"
}

Custom Prompt

Style your shell prompt with colors and info.

PS1='\[\e[32m\]\u@\h\[\e[0m\]:\w$ '

Don't worry about getting it perfect. You can always edit your profile later from the dashboard.

Activate Your Environment

Open a terminal on any machine and run:

curl -sL gh-env.sh | sh

This downloads and runs the Ghost-Env activation script. Here's what happens:

1.
CLI Installation
The script installs the gh-env CLI tool to ~/.ghostenv/bin/
2.
Device Code Display
A QR code and a short code (like XKCD-1337) appear in your terminal.
3.
Browser Authorization
Scan the QR code or visit gh-env.sh/auth and enter the code.
4.
Profile Activation
Once authorized, your profile scripts are downloaded, verified, and applied to your shell.

_device_authorization_flow

Ghost-Env uses a secure device code flow for authentication. This means you never type your password in the terminal.

// What you'll see in the terminal:

┌─────────────────────────────────────────────────────┐
│                                                     │
│   Scan QR code or visit the URL to authenticate    │
│                                                     │
│   URL:  gh-env.sh/auth                           │
│   Code: XKCD-1337                                   │
│                                                     │
└─────────────────────────────────────────────────────┘

[👻~] Waiting for authorization...

Option A: QR Code

1. Open your phone's camera
2. Point at the QR code
3. Tap the link that appears
4. Log in and approve

Option B: Manual Entry

1. Open gh-env.sh/auth
2. Click "Device Authorization"
3. Enter the code from terminal
4. Click "Authorize"

Once authorized, the terminal will automatically continue and activate your environment. Your device is now registered and will appear in your Dashboard under "Devices".