🟥 Neocities Red

A modern Neocities CLI

A refactored and extended fork of the official https://github.com/neocities/neocities-ruby

Built for performance, reliability, and real-world workflows (especially static site generators).

• Parallel uploads (3–5 concurrent workers)
• Smart diffing (only upload what changed)
• Automatic retries (handles flaky Neocities API / SSL issues)
• Recursive uploads out of the box
• SSG-friendly (Jekyll, Hugo, Eleventy, etc.)
• Clean, extensible architecture

• Ruby 3.4+ (tested, supports 4.x)

Not a programmer?

• Install Ruby here - https://www.ruby-lang.org/en/
• For Windows you should have installed MSYS2 and MINGW

Using version managers:

• mise
• asdf

gem install neocities-red

neocities-red

• Modernized dependencies
• Improved Ruby compatibility (3.4 → 4.x)
• Cleaner architecture for future features

• Multi-threaded (3–5 concurrent uploads)
• Fully recursive
• Rewritten upload pipeline

Designed for static site workflows.

neocities push --optimized --ignore-dotfiles .
neocities push -e node_modules -e .git .

Preview changes before uploading:

neocities diff .

Handles:

• SSL errors
• timeouts
• unstable Neocities API

No more broken deploys due to transient failures.

require 'neocities-red'

client = Neocities::Client.new(api_key: 'YOUR_API_KEY')

client.upload(local_path, remote_path)
client.delete(remote_path)
client.list(remote_path)
client.info(sitename)
client.push(local_path)

client = Neocities::Client.new(
  sitename: 'o200',
  password: 'secret'
)

service = Neocities::Services::FileList.new(
  client,
  path: '.',
  detail: true
)

files = service.show

1. Check existing issues
2. Comment: "I'll take this"
3. Fork the repo
4. Create a feature branch
5. Implement + test
6. Open a PR

MIT — see LICENSE

Built for the Neocities community.