Ghost-CLI

1.29.2 verified Sat Apr 25 auth: no javascript

Ghost-CLI is the official command-line tool for installing, updating, and managing Ghost (content management system) on production and local environments. Current stable version is 1.29.2, with regular patch releases (approximately monthly). It manages the entire lifecycle: setup, configuration, backups, SSL via Let's Encrypt, Nginx, and Systemd on Ubuntu. Key differentiators: single-command install/update, recommended stack enforcement (Ubuntu, Nginx, MySQL, Node.js), and minimal configuration options to reduce maintenance complexity. Supports both production and local installs.

Common errors

error ghost: command not found ↓

cause Ghost-CLI not installed globally or PATH not set.

fix

Run 'npm install -g ghost-cli@latest' and ensure npm global bin directory is in PATH.

error Fatal error: Node version must be >=20.11.1 ↓

cause Node.js version is too old.

fix

Update Node.js to 20.11.1, 22.11.0, or 24.0.0 using nvm or installer.

error ghost install: EACCES: permission denied ↓

cause Missing permissions to write to /etc/nginx or system directories.

fix

Run 'ghost install' with sudo or install locally with 'ghost install local'.

error Error: connect ECONNREFUSED 127.0.0.1:3306 ↓

cause MySQL/MariaDB not running.

fix

Start MySQL service: 'sudo systemctl start mysql' or 'sudo service mysql start'.

error Error: getaddrinfo ENOTFOUND api.github.com ↓

cause Internet connectivity or DNS issue during update/install.

fix

Check internet connection and DNS settings. If behind proxy, set HTTP_PROXY/HTTPS_PROXY.

Warnings

breaking Ghost-CLI requires Node.js ^20.11.1 || ^22.11.0 || ^24.0.0. Older Node versions are not supported. ↓

fix Update Node.js to a supported version (20.11.1+, 22.11.0+ or 24.0.0+).

deprecated Ghost-CLI does not support Ghost versions < 1.0.0. ↓

fix Use Ghost-CLI only with Ghost 1.0.0 and above. For older versions, use legacy tooling.

gotcha Ghost-CLI is designed for the recommended stack (Ubuntu, Nginx, MySQL, Systemd). Other environments may not work correctly. ↓

fix Use the recommended stack for production, or use 'ghost install local' for development.

breaking Ghost 5.x introduced a new content API and admin client; Ghost-CLI v1.28+ is required for compatibility. ↓

fix Update Ghost-CLI to >=1.28.0 to manage Ghost 5.x.

gotcha The 'ghost backup' command may fail for Ghost v6+ if the database configuration has changed. ↓

fix Ensure the database config (docker-compose or direct) is properly set and accessible.

deprecated The --auto option has been removed in recent versions; use environment variables or config file. ↓

fix Set environment variables (e.g., GHOST_URL, MAILGUN_SMTP_USERNAME) or use a config.local.json.

gotcha Ghost-CLI uses 'portfinder' which may conflict with firewall or Docker networking. ↓

fix If port usage issues occur, specify port via --port or adjust firewall rules.

Install

npm install ghost-cli

yarn add ghost-cli

pnpm add ghost-cli

Quickstart

Shows global install, production vs local setup, and basic commands for Ghost management.

npm install -g ghost-cli@latest
# Production install (interactive prompts)
ghost install
# Local install for development
ghost install local

# Or setup a directory:
mkdir my-ghost
cd my-ghost
ghost install --no-setup-nginx --no-setup-ssl --no-setup-systemd

# Update Ghost to latest version:
ghost update

# Check status:
ghost status