🟥 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).

---

✨ Key Features

• 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

---

Installation

Requirements

• 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

---

Install

gem install neocities-red

---

Quick Start

neocities-red

---

What's New

0. Full Refactor

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

---

1. upload — Parallel & Recursive

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

---

2. push

Designed for static site workflows.

Flag	Description
--optimized	Upload only changed/missing files
--ignore-dotfiles	Skip .git, .env, etc.
-e <folder>	Ignore folder recursively

Examples

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

---

3. diff — Local vs Remote

Preview changes before uploading:

neocities diff .

---

4. Built-in Retries

Handles:

• SSL errors
• timeouts
• unstable Neocities API

No more broken deploys due to transient failures.

---

Library Usage

Basic Client

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)

---

Advanced: Services

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

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

files = service.show

---

Contributing

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

---

License

MIT — see LICENSE

---

Acknowledgements

Built for the Neocities community.