Ghost CLI — Complete Command-Line Installation and Management Guide

In this tutorial, you'll learn how to use the Ghost CLI — the official command-line tool for installing, updating, and managing Ghost sites — from local development setup to production deployment commands.

What You'll Learn

• Installing the Ghost CLI globally with npm
• The difference between ghost install local and ghost install
• Starting, stopping, and restarting Ghost processes
• Checking Ghost version and status
• Managing multiple Ghost sites on one server
• Updating Ghost and rolling back versions
• Ghost CLI configuration and debugging
• Common CLI commands and their flags

Why It Matters

The Ghost CLI is the primary way to interact with a Ghost installation. Whether you are setting up a local development environment, deploying to production, or troubleshooting a server issue, the CLI is your control panel for everything outside the browser-based admin. Knowing the CLI commands well saves you time, prevents mistakes, and gives you insight into how Ghost manages its processes, versions, and configuration.

Real-World Use

You need to migrate a Ghost site from a staging server to production. You SSH into the production server, install the Ghost CLI, run ghost install with the production URL and database credentials, then export the staging content and import it into production. The whole process takes under 30 minutes because the CLI handles database setup, Nginx configuration, SSL certificates, and process management automatically.

Learning Path

flowchart LR
  A["What is Ghost?"] --> B["Ghost Architecture"]
  B --> C["Ghost CLI
You are here"]:::current
  C --> D["Ghost Editor"]
  D --> E["Ghost Installation"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

Installing the Ghost CLI

The Ghost CLI is an npm package that you install globally. First, make sure Node.js and npm are installed on your system.

# Check Node.js version (requires 18.x or 20.x)
node --version

# Check npm version
npm --version

# Install Ghost CLI globally
npm install -g ghost-cli@latest

After installation, verify it works:

ghost --version

This shows the Ghost CLI version, like 2.1.0. The Ghost CLI is separate from the Ghost CMS version. You can use a recent CLI to install any compatible Ghost version.

Ghost Install vs Ghost Install Local

The Ghost CLI has two installation modes.

ghost install local

This is for local development on your machine. It:

• Creates a new directory with a Ghost installation
• Uses SQLite as the database (no MySQL needed)
• Configures Ghost to run on http://localhost:2368
• Starts Ghost as a foreground process or background service
• Does NOT set up Nginx or SSL

# Create a directory for your Ghost site
mkdir my-ghost-site
cd my-ghost-site

# Install Ghost locally
ghost install local

The first time you run this, Ghost installs the latest version, creates the SQLite database, generates configuration files, and starts the server. You see output like:

✔ Checking system Node.js version
✔ Checking current Ghost installation
✔ Removing old Ghost installation
✔ Setting up install directory
✔ Downloading and installing Ghost v5.x
✔ Setting up SQLite database
✔ Running database migrations
✔ Starting Ghost

Ghost is running in development mode at http://localhost:2368

ghost install

This is for production servers. It:

• Requires MySQL 8.0+
• Configures Nginx as a reverse proxy
• Sets up SSL with Let's Encrypt (optional)
• Configures a systemd service for auto-start
• Sets up email transport

# Install Ghost in production mode
sudo ghost install

The production installer is interactive — it prompts you for your site URL, database credentials, and other settings.

Core Commands

Managing the Ghost Process

Once Ghost is installed, these commands control the running process:

# Start Ghost
ghost start

# Stop Ghost
ghost stop

# Restart Ghost
ghost restart

# Check Ghost status
ghost status

The ghost status command shows:

Ghost is running in production mode at https://yoursite.com
Process ID: 12345
Listening on: 0.0.0.0:2368
URL: https://yoursite.com

Version Management

# Check current Ghost version
ghost version

# Update Ghost to the latest version
ghost update

# Update to a specific version
ghost update 5.x

# Roll back to the previous version
ghost update --rollback

The ghost update command handles the entire update process:

1. Downloads the new version
2. Backs up the current installation
3. Runs database migrations
4. Restarts the Ghost process
5. Verifies the site is running

# Example output of ghost update
✔ Checking System Node.js version
✔ Checking MySQL version
✔ Checking current Ghost version (5.30.0)
✔ Checking for update (5.31.0 available)
✔ Running ng check
✔ Downloading and installing Ghost v5.31.0
✔ Stopping Ghost
✔ Removing old Ghost installation
✔ Setting up install directory
✔ Running database migrations
✔ Restarting Ghost
✔ Checking Ghost is running

Ghost updated successfully from 5.30.0 to 5.31.0

Configuration Commands

# Show current configuration
ghost config show

# Set a specific config value
ghost config set url https://mysite.com
ghost config set mail__transport SMTP
ghost config set mail__options__host smtp.example.com

# Get a specific config value
ghost config get url

Setup Commands

# Setup Nginx configuration
ghost setup nginx

# Setup SSL certificate with Let's Encrypt
ghost setup ssl

# Setup systemd service
ghost setup systemd

# Setup email transport
ghost setup mail

You can run these individually if you skipped them during installation or need to reconfigure.

Ghost Install Directory Structure

When you run ghost install, it creates this structure in your Ghost directory:

my-ghost-site/
├── content/                 # All user content and data
│   ├── data/                # SQLite database (local only)
│   ├── images/              # Uploaded images
│   ├── logs/                # Application logs
│   ├── settings/            # YAML settings files
│   └── themes/              # Installed themes
├── config.production.json   # Production configuration (or config.development.json)
├── index.js                 # Ghost app entry point
├── current -> versions/5.x  # Symlink to active version
└── versions/                # Installed Ghost versions

The current symlink is important — it points to the currently active Ghost version. When you run ghost update, the CLI downloads the new version into versions/ and updates the symlink.

Advanced CLI Usage

Running Ghost with Docker

The CLI also supports Docker-based setup:

# Check Docker setup
ghost setup docker

# Install with Docker
ghost install --docker

Managing Logs

# Show recent logs
ghost log

# Follow logs in real time
ghost log --tail

# Show error logs only
ghost log --errors

Development Mode

# Run Ghost in development mode
ghost run

# Run with debug output
NODE_ENV=development ghost run

The ghost run command starts Ghost in the foreground — useful for testing and development because you see console output directly. Press Ctrl+C to stop.

Multi-Site Management

You can run multiple Ghost sites on one server by creating separate directories for each:

# Site 1
mkdir /var/www/site1 && cd /var/www/site1
ghost install --url https://site1.com

# Site 2
mkdir /var/www/site2 && cd /var/www/site2
ghost install --url https://site2.com --port 2370

Each site gets its own directory, database, and Node.js process.

Ghost CLI Configuration File

The CLI itself has a configuration file at ~/.ghost/config.json. This stores:

{
  "telemetry": true,
  "disableAnalytics": false,
  "force": false,
  "cliVersion": "2.1.0"
}

You rarely need to edit this directly, but you can:

ghost config --help

Common Mistakes

1. Running ghost install without sudo on production: The production installer needs root access to configure Nginx, systemd, and SSL. If you forget sudo, the CLI tells you and asks you to re-run with sudo. Always use sudo ghost install for production.

2. Using ghost install local on a production server: The local flag is for development only. It skips Nginx, SSL, MySQL, and systemd setup. Running a production site with ghost install local means no reverse proxy, no HTTPS, and SQLite instead of MySQL.

3. Installing Ghost CLI globally with the wrong Node version: Ghost requires Node.js 18.x or 20.x LTS. Installing the CLI with an older Node version produces cryptic errors. Always check node --version first.

4. Running ghost update without a backup: While the CLI creates a backup before updating, database corruption can still occur. Always create a manual database backup before major updates, especially if you run MySQL.

5. Editing files in the current directory: The current directory is a symlink to the installed Ghost version. When you update Ghost, the symlink changes. Any edits you make to files in current/ are lost. Customizations belong in content/ or your theme.

Practice Questions

1. What is the difference between ghost install and ghost install local? Answer: ghost install local sets up Ghost for development with SQLite, no Nginx, no SSL, and no systemd. ghost install sets up Ghost for production with MySQL, Nginx reverse proxy, SSL certificates, and systemd service management.

2. How do you check which version of Ghost is running on your server? Answer: Run ghost version in your Ghost installation directory. This shows both the Ghost CLI version and the installed Ghost CMS version.

3. What does ghost update do step by step? Answer: It checks the current version, downloads the new version, backs up the installation, runs database migrations, restarts Ghost, and verifies the site is running. You can roll back with ghost update --rollback.

4. Challenge: Install Ghost locally using ghost install local. Then create a second Ghost site in a different directory on port 2370. Start both sites simultaneously, verify both are accessible at http://localhost:2368 and http://localhost:2370, and write a Shell Script that starts both sites with a single command.

FAQ

Mini Project

Your task: Create a complete Ghost CLI reference document for your development workflow.

1. Install Ghost locally using ghost install local.
2. Practice each of these commands and document the output: ghost status, ghost version, ghost log, ghost config show, ghost ls.
3. Stop Ghost, start it again, then restart it.
4. Create a bash alias file that defines shortcuts for the most common Ghost commands (e.g., alias gstart='ghost start', alias gstop='ghost stop', alias gstatus='ghost status').
5. Write a one-page CLI cheat sheet that you can refer to during the rest of this course.

This exercise makes you comfortable with the CLI before moving to deeper configuration tasks.

What's Next

Now that you know how to use the Ghost CLI, it is time to create content:

Continue to Lesson 4: Ghost Editor — Master the Koenig editor, markdown, cards, and the publishing workflow.

Related lessons:

• Ghost Admin — Explore the admin dashboard settings
• Posts and Pages — Understand the two content types