$ CLI Reference
Complete reference for the gh-env command line tool.
_installation
The CLI is automatically installed when you run the activation command. For manual installation:
curl -sL gh-env.sh | shcurl -sL gh-env.sh/install | shInstallation Paths
| Mode | CLI Path | Token Path |
|---|---|---|
| Normal | ~/.ghostenv/bin/gh-env | ~/.ghostenv/.token |
| Zero-Trace | /tmp/ghostenv.xxx/bin/gh-env | /tmp/ghostenv.xxx/.token |
| Read-Only | (inline) | $GHOST_TOKEN (env var) |
_command_reference
gh-env activate [profile]Activate a profile in the current shell. Downloads scripts, verifies signatures, and sources them.
gh-env deactivateDeactivate the current profile. Runs cleanup scripts and restores the previous shell state.
gh-env statusShow current status including active profile, mode, and token validity.
gh-env profilesList all available profiles for your account.
gh-env refreshRefresh the access token using the stored refresh token. Usually happens automatically.
gh-env logoutLog out from this device. Removes stored tokens and deactivates the session.
gh-env versionShow the installed CLI version.
_activation_modes
| Mode | Command | Disk Writes | Use Case |
|---|---|---|---|
| Normal | curl -sL gh-env.sh | sh | Yes (~/.ghostenv/) | Personal machines, persistent servers |
| Zero-Trace | curl -sL gh-env.sh/0 | sh | Yes (/tmp/) | Shared computers, temporary access |
| Read-Only | curl -sL gh-env.sh/r | sh | No | Immutable systems, containers |
Mode Details
Normal Mode
- + CLI and scripts installed to
~/.ghostenv/ - + Tokens stored persistently for auto-login
- + Add to shell rc for auto-activation on new terminals
- + Device registered and visible in dashboard
Zero-Trace Mode
- + All files in
/tmp/ghostenv.RANDOM/ - + Automatic cleanup on exit (even on Ctrl+C)
- + Device unregistered from server on exit
- + Sensitive files securely shredded
Read-Only Mode
- + Zero disk writes - everything in memory
- + Scripts evaluated inline via
eval - + Tokens stored in shell environment variables
- + Works on read-only filesystems and containers
_environment_variables
These environment variables can be used to configure Ghost-Env behavior:
| Variable | Default | Description |
|---|---|---|
| GHOST_API_URL | gh-env.sh/api/v1 | API endpoint URL |
| GHOST_HOME | ~/.ghostenv | Installation directory |
| GHOST_TOKEN | (from file) | Override access token (read-only mode) |
| GHOST_PROFILE | default | Default profile to activate |
| GHOST_MODE | (auto) | Current mode (normal/zero-trace/read-only) |
| GHOST_DEBUG | 0 | Enable debug logging (set to 1) |
_troubleshooting
"Command not found: gh-env"
The CLI isn't in your PATH. Add it:
"Token expired"
Your access token has expired and couldn't be refreshed. Re-authenticate:
"Signature verification failed"
The script signature doesn't match. This could indicate tampering. Try refreshing:
If this persists, contact support - your profile may need to be re-signed.
"Permission denied"
Can't write to the installation directory. Check permissions or use read-only mode:
"Device code expired"
You took too long to authorize. Device codes expire after 10 minutes. Run the command again:
_shell_integration
To automatically activate Ghost-Env when opening a new terminal, add to your shell config: