Publish your static site to Neocities from the terminal
Neocities Red is a fast, reliable Neocities CLI and Ruby client. Upload files in parallel, sync only what changed, and forget flaky API timeouts — built for Jekyll, Hugo, Eleventy and any other static site generator.
gem install neocities-redBuilt for real-world workflows
Everything the official CLI does — and everything it was missing.
Parallel uploads
Up to 5 concurrent workers push your site without waiting on each file.
Automatic retries
Transient Neocities API and SSL failures are retried so deploys don't flake out.
Smart diffing
Only upload files that actually changed — faster pushes, less API churn.
Recursive uploads
Upload whole directories in one command, matching your folder structure.
SSG-friendly
Works out of the box with Jekyll, Hugo, Eleventy, Astro and more.
.gitignore-aware push
Respects your ignore rules by default — no secrets or build cruft uploaded.
Incremental pull
Skips files unchanged since your last pull — backup your site in seconds.
Ruby client + CLI
A clean API client with namespaced services for scripting and automation.
From zero to deployed in three commands
Authenticate once, then push your whole site whenever you build it.
gem install neocities-red
# first authenticated command prompts for your sitename and password
neocities-red push .
Every command you need
Push, pull, diff, upload and manage your site with an explicit, documented CLI.
Command overview
push— upload a whole directory (gitignore-aware)upload— upload individual files or folderspull— download your site (incremental)diff— compare local files with the serverlist— list remote files and metadatadelete— remove files from your siteinfo— site stats and infopurge— wipe a development sitelogout— remove the stored API key
Built for humans
neocities-red help <command>— explicit per-command help--dry-run— preview before you deploy--optimized— skip files already on the server--prune— delete remote files missing locally-e/--exclude— exclude paths (repeatable)- Spinners, colored output, and a friendly
pizzaeaster egg 🍕
Why Neocities Red?
A refactored and extended fork of the official neocities-ruby gem.
Faster, more reliable deploys
Parallel uploads, automatic retries on 429/5xx and SSL hiccups, and SHA1-based optimized uploads mean your site ships quickly — even on flaky connections.
Safer by default
push respects your .gitignore rules, so
credentials and build artifacts never reach the server. diff
lets you inspect changes before anything touches the remote.
Open and maintained
MIT-licensed, CI-tested on Ruby 3.4, 3.5 and 4.0 across Linux, macOS, Windows and FreeBSD — with an active changelog and a welcoming contributing guide.
Scriptable
Use the Ruby client directly,
or drive the CLI in CI with --api-key or
NEOCITIES_API_KEY.
Ready to deploy?
Install the gem, log in once, and push your static site to Neocities.
Install Neocities Red Star on GitHub