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

• CLI with explicit command help (neocities-red help <command>)
• Parallel uploads (up to 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.)
• Namespaced services grouped by domain (file/, site/, common/)
• Incremental pull — skips files unchanged since your last pull
• .gitignore-aware push — respects your ignore rules by default

• Ruby 3.4+ (CI-tested against 3.4, 3.5, and 4.0 on Linux, macOS, Windows, and FreeBSD)

Not a programmer?

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

gem install neocities-red

neocities-red help
neocities-red help push

On first authenticated command you'll be prompted for your sitename/username and password — the resulting API key is stored locally for future runs.

neocities-red push .

The CLI resolves credentials in this order:

1. --api-key flag — neocities-red --api-key <key> push .
2. NEOCITIES_API_KEY environment variable
3. Stored config — the API key saved by a previous interactive login
4. Interactive login — prompts for sitename/username and password

For non-interactive logins you can also set:

The config file is stored per platform:

Remove the stored key with:

neocities-red logout -y

push      Recursively upload a local directory to your site
upload    Upload individual files/folders to your site
delete    Delete files from your site
diff      Compare your local directory with your site
list      List files from your site
info      Show information and stats for your site
pull      Get the most recent version of files from your site
purge     Remove all files from your site (development only)
logout    Remove the stored API key from the config
version   Print the gem version
pizza     Order a free pizza
help      Show help for a command

Recursively upload a local directory to your Neocities site. Respects .gitignore rules by default.

neocities-red push .
neocities-red push . --optimized --ignore-dotfiles
neocities-red push . -e node_modules -e .git
neocities-red push . --dry-run
neocities-red push . --prune

Compare a local directory with the remote site and show added, modified, and removed files.

neocities-red diff .
neocities-red diff ./my-website --ignore-dotfiles
neocities-red diff . -e secret.txt

Upload an individual file or folder to your site.

neocities-red upload index.html
neocities-red upload assets/ images/assets

List files from your Neocities site.

neocities-red list
neocities-red list images -d
neocities-red list -a

Show information and statistics for a site (defaults to your own site).

neocities-red info
neocities-red info fauux

Download the most recent version of files from your site. Skips files that haven't changed since your last pull.

neocities-red pull
neocities-red pull --quiet

Delete one or more files from your site.

neocities-red delete old.html
neocities-red delete old.html archived/old.css

Delete everything from your site. Intended for development sites only — use with care.

neocities-red purge -y
neocities-red purge -y --dry-run

Remove the stored API key from the config. Requires confirmation.

neocities-red logout -y

neocities-red version   # print the gem version
neocities-red pizza     # order a free pizza (easter egg)

require 'neocities-red'

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

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

The client supports both API-key (api_key:) and basic-auth (sitename:/password:) authentication, retries transient failures (429/5xx) automatically, and exposes low-level helpers like upload_hash, delete_wrapper_with_dry_run, key, and download.

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

service = NeocitiesRed::Services::File::List.new(
  client,
  '.',
  true
)

files = service.show

Current service namespaces:

• NeocitiesRed::Services::File (Uploader, FolderUploader, List, Remover)
• NeocitiesRed::Services::Site (Pusher, Differencer, Exporter, Informer)
• NeocitiesRed::Services::Common (Exclusions, WorkerPool, Pizza)

bundle install
bundle exec rspec     # run the test suite
bundle exec rubocop   # run the linter
bundle exec ruby bin/neocities-red   # run the CLI from source

See CHANGELOG.md for release history.

see CONTRIBUTING.md

MIT — see LICENSE

Built for the Neocities community.