TryGhost/Ghost-CLI

Ghost-CLI

Basic Setup

• npm install -g ghost-cli@latest
• ghost install (for a production linux setup, including Nginx, SSL, and Systemd)
• ghost install local (for a local setup, useful for theme development/testing)

NOTE: This CLI is not designed to work with any Ghost versions < 1.0.0

Running behind a proxy

Set NODE_USE_ENV_PROXY=1 (or NODE_OPTIONS=--use-env-proxy) so Node picks up HTTP_PROXY, HTTPS_PROXY and NO_PROXY from the environment. This requires Node 22.21.0 or Node 24.5.0 and above.

Documentation

• Complete Setup Guide
• Command Reference
• Knowledgebase
• Forum
• Migration bundle format — ghost migrate-export usage, Ghost 6.61.0+ fidelity and --leave-stopped cutover

Project Goals

The objective of the Ghost CLI project is to make setting up and maintaining a Ghost site as straight forward as possible for people who do not want to use Ghost(Pro).

Ghost-CLI is aimed at people who are comfortable in a command line environment, and therefore some technical knowledge is assumed. The design goal of Ghost CLI was to make it possible to install or update Ghost in a single command.

In order to keep these goals obtainable & maintainable by Ghost's small team, we have a recommended system stack that Ghost-CLI works with, and minimal configuration options.

Recommended stack

We officially recommend the stack described here for production installs.

The team behind Ghost CLI only supports this stack. This restriction is very deliberate, as every additional option for configuration or divergent piece of code required to support an additional environment creates exponential complexity and maintenance overhead.

Our primary focus for the project is ensuring that everyone that uses the recommended system stack is able to install, configure, start, stop, restart, update & list their Ghost sites. This includes developing better testing to ensure we are able to prevent regressions, and stabilising the code to ensure that edge cases within the recommended stack are accounted for.

The secondary focus is on improving the CLI itself. We want to ensure that the UI, configuration options, flags, flows, prompts, messages and other behaviours are working for both manual and programmatic use. This also includes improving the documentation to make it easy to use the tool, discover advanced options & debug any common issues.

Anything that falls outside of these two areas is not being actively worked on at present.

Triaging & prioritisation

• Issues which affect many users with our recommended stack are given first priority
• Issues which affect small numbers of users are prioritised based on the impact vs the difficulty - i.e. quick fixes will be prioritised, complex issues may be closed and labelled with later & recommended-stack.
• Issues around documented & understood environment or configuration issues will be closed and labelled with known-issue, users will be directed to the docs & forum.
• Issues that request modifications in order to support other stacks stack will be closed and labelled with later & other-stack.
• Issues proposing new features or enhancements will be labelled as such, and in most cases also closed with later.

Help & Support

We aren't able to provide support in GitHub, but we do keep track of common issues with the known-issue label and regularly update documentation & error messages to be clearer.

The documentation for Ghost-CLI can be found at https://ghost.org/docs/ghost-cli/. Community support can be found in our forum.

Developer Setup (for contributing)

1. Fork this repo
2. git clone https://github.com/<your-username>/Ghost-CLI path/to/your/workspace
3. cd path/to/your/workspace
4. pnpm install

To run the CLI for testing:

• pnpm link
• ghost <command> (can run anywhere on the system)

Running tests

pnpm test

Publishing a new version

Releases are cut from the Release workflow. Run it from main and pick a bump type:

• auto (default) — minor if there are ✨ commits since the last release, otherwise patch
• patch / minor / major — force a specific bump
• dry run — do everything except push, to preview the version

From there it's automatic:

1. The Release workflow runs the tests, then pushes a chore(release): x.y.z commit to main
2. The Publish workflow publishes that version to npm, creates the vx.y.z tag, and creates the GitHub Release
3. Release notes are generated by scripts/release-notes.js from the emoji-prefixed commits since the previous tag — see the commit message convention

To preview the notes for a release locally:

pnpm release-notes v1.30.0 v1.30.1

The Release workflow pushes with the GST_TOKEN PAT. A push made with the default GITHUB_TOKEN would not trigger the Publish workflow, so that token needs write access to this repo.

Publishing a prerelease

Prereleases are manual — the Release workflow only cuts stable versions.

1. Branch off main and set the prerelease version in package.json by hand, e.g. 1.31.0-beta.0
2. Push the branch
3. Run the Publish workflow via "Run workflow", selecting your branch as the ref, with mode: publish and npm_tag: next

Install it with:

npm install -g ghost-cli@next

Keep the prerelease on a branch — a prerelease version in a chore(release): commit on main would be published under latest. The manual dispatch also skips git tagging and the GitHub Release, so a prerelease leaves no tag behind.

Use mode: dry-run to preview the tarball without publishing.

Copyright & License

Copyright (c) 2013-2026 Ghost Foundation - Released under the MIT license. Ghost and the Ghost Logo are trademarks of Ghost Foundation Ltd. Please see our trademark policy for info on acceptable usage.