Neurotic Pantaloon Maker

    steady-cli

    2.3.0 • Public • Published

    Version GitHub Coverage Node

    CLI for programmatically maintaining Ghost sites

    steady-cli is an all-in-one tool for Ghost theme development and maintaining Ghost sites programmatically.

    Benefits

    • Create and locally develop a new Ghost theme.
    • Maintain your Ghost site programmatically without having to go back and forth to the Admin UI.
    • Easily integrate into an existing build process.

    Prerequisites

    • NodeJS/npm
    • A existing Ghost site with administrator access

    Installation

    npm install -g steady-cli

    or on a per-project basis:

    npm install --save-dev steady-cli

    Create an integration in your site (for publish)

    • Go to the Integration Settings link in your Ghost site and click Add custom integration.
    • Give the new integration any name you want e.g. Mindspun and hit 'Create'.
    • Note the 'Admin API Key' to be used later.

    This integration will be used to publish your theme to an existing site.

    Usage

    Create a new theme

    From an empty directory where you want your setup to live:

    steady setup

    The setup command will install the following:

    • a local version of Ghost
    • a new theme under content/data/ghoststead

    If you want to check your theme into git (and you should), check in the contents of the content/data/ghoststead directory only. i.e. the ghoststead directory should be the top level directory in your git repository.

    Start/Stop/Restart Ghost

    Start the local version of Ghost that was installed via setup by running the command:

    steady start

    The start command will run a development version of Ghost in the background. Log files may be found under content/logs.

    You can stop your Ghost instance via:

    steady stop

    Restart Ghost via:

    steady restart

    If Ghost is not already running, restart just starts Ghost.

    Theme development

    In order to develop a new theme, you have to build it. Depending on your theme the build may perform many steps but at a minimum it needs to compile Sass files into css. steady-cli can watch your theme for file changes and automatically build your theme when something changes. Run:

    steady develop

    The develop command runs in the foreground and automatically rebuilds your theme whenever a source file is modified. You can easily extend this process by adding additional grunt tasks in content/themes/ghoststead/grunfile.js.

    If your theme name changes from the default ghoststead, you can add set the new theme name in the .steadyrc file via:

    {
        "themeName": "mytheme"
    }

    where mytheme is replaces by the name of your theme. Your theme should be located - for instance, checked out if using source control - in content/themes along side the ghoststead and casper themes.

    Upload a theme

    To upload a theme using the steady CLI, you have to create a integration in your site and set both siteUrl and adminApiKey in your .steadyrc file. The .steadyrc file was automatically created when running the 'setup' command. You may recreate the the rc file via:

    steady initrc
    

    Once your .steadyrc file is configured, you can upload a built theme via:

    steady publish
    

    This command will upload the zipped theme from your theme's dist directory using the configuration in the theme package.json file.

    If you want to upload a different theme by its path, you can run:

    steady publish-theme /path/to/theme.zip

    NOTE None of the above commands will activate the uploaded theme.

    Using a different working directory

    By default, the steady command uses the current working directory as the location of the Ghost installation and tries to find your theme relative to that directory. In some cases, it may be helpful to run steady from another directory and reference your local Ghost installation. One such example is having a .steadyrc file inside of theme that is symbolic linked into content\themes.

    To run steady from a different directory than your Ghost installation specify the working directory in one of two ways:

    • Use the --workdir command line option
    • Use specify "workDir" in your .steadyrc file.

    If both options are used - i.e. you specify workdir on the command line and you have workDir in your .steadyrc file - then the command line option takes precedence and the .steadyrc file option is simply ignored.

    Reset Ghost

    The reset command will reinitialize the Ghost SQLITE3 database, allowing the owner to go through the setup process again. Ghost must be stopped when running this command.

    steady reset

    New in 1.9.0

    Get help

    steady --help

    Troubleshooting

    Error: Request failed with status code 404

    • Ensure that your site is up and running (common problem when running locally)
    • Re-run the command with the verbose -v option and ensure all information is correct.

    In particular, ensure that the API version is correct. The API version defaults to v3 so if you're still on v2 that API won't yet exist and you'll get a 404 error.

    You can specify the API version in the .steadyrc file like:

    {
        "version": "v2"
    }

    Roadmap

    steady-cli will gradually be expanded to handle other aspects of Ghost administration, specifically:

    • Download/upload routes.yaml
    • Download/upload redirects.json

    Pull requests welcome.


    This repository is maintained by Mindspun.

    Install

    npm i steady-cli

    DownloadsWeekly Downloads

    1

    Version

    2.3.0

    License

    MIT

    Unpacked Size

    59 kB

    Total Files

    46

    Last publish

    Collaborators

    • mindspun