The Neocities CLI

Manage your site using a shell terminal

Neocities has a CLI for power users that want to upload sites using a command line.


  • Push support - uploads an entire directory. Great for static site generators.
  • HTTP persistence - the CLI reuses a single HTTP connection, improving performance.
  • Check before upload - checks if the file data matches before uploading.
  • Gitignore parsing - automatically skips files in root gitignore file for git repositories.

Install Instructions

If you're using a newer version of OSX or already have Ruby installed, just run this command to install:

gem install neocities

If you get a permission error, you may need to run the command as superuser:

sudo gem install neocities

After installation, just run the command to get started:

$ neocities

| o_o |   Neocities

  push        Recursively upload a local directory to your site
  upload      Upload individual files to your Neocities site
  delete      Delete files from your Neocities site
  list        List files from your Neocities site
  info        Information and stats for your site
  logout      Remove the site api key from the config


If you're using Windows, you can install ruby with something like the Ruby Installer, and then run the above command.

Linux / BSD

Most Linux / BSD distributions come with Ruby packages. For example, with Ubuntu:

sudo apt-get install ruby-full A full list of available install options for ruby is here.

Git Hooks

If you want to create a git hook to automatically upload your site to Neocities when you run "git push", you can run this command in the root directory of your git repo:

printf '#!/bin/sh\nneocities push .' >.git/hooks/pre-push && \
chmod u+x .git/hooks/pre-push

If the files you're pushing are in a subdirectory of the root git repo, replace the "." with the subdirectory. For example, with Jekyll (which typically uses _site):

printf '#!/bin/sh\nneocities push _site' >.git/hooks/pre-push && \
chmod u+x .git/hooks/pre-push

Note: You will need to be logged in for the git hook to work, so run "neocities push" on the directory you want to upload before installing this hook. This will be fixed in a later version of the CLI.