Neocities API Manager

This directory contains tools to manage your Neocities website via the Neocities API.

🌐 Web Interface (Recommended!)

The easiest way to manage your Neocities site is with the web UI!

Start the Web UI:

.\start-ui.bat

Then open your browser to http://localhost:8080

Features:

• ✨ Drag & drop file uploads
• 📂 Visual file browser
• 🗑️ One-click file deletion
• 🎨 Clean, minimalistic design
• 💻 Very low resource usage (~150 MB total)

For detailed Web UI instructions, see WEB-UI-GUIDE.md

---

Files

• neocities-apikey - Your Neocities API key (keep this secure!)
• neocities-manager.py - Python script to manage your Neocities site
• neocities-manager.js - Node.js script to manage your Neocities site (alternative)
• test-api.js - Simple test script for the Node.js version

Requirements

Choose ONE of the following:

Option 1: Python (Recommended)

• Python 3.6 or later
• No external dependencies required (uses built-in urllib)

Option 2: Node.js

• Node.js 12 or later
• No external dependencies required (uses built-in modules only)

Web UI (Optional)

If you want to use the Web UI (server.py):

• Python 3.6 or later
• flask and flask-cors

Install with:

pip install -r requirements.txt

Usage

Quick Start

Test the connection:

.\neocities.bat list

Upload the test page:

.\neocities.bat upload test-page.html

After uploading, visit your site to see the test page!

Examples

List all files on your site:

.\neocities.bat list

List files in a specific directory:

.\neocities.bat list images

Upload a single file:

.\neocities.bat upload index.html

Upload a file with a different name on the server:

.\neocities.bat upload local-style.css css/style.css

Upload an entire directory:

.\neocities.bat upload-dir ./my-website

Upload a directory to a specific path on the server:

.\neocities.bat upload-dir ./assets images

Delete files:

.\neocities.bat delete old-file.html another-file.css

Get help:

.\neocities.bat help

Alternative: Direct Python Usage

If you prefer to call Python directly:

C:\Users\didac\AppData\Local\Programs\Python\Python312\python.exe neocities-manager.py list

Or if Python is in your PATH:

python neocities-manager.py list

Node.js Version

Same commands as Python, but use node instead:

node neocities-manager.js list
node neocities-manager.js upload index.html
node neocities-manager.js upload-dir ./my-website
node neocities-manager.js delete old-file.html

API Key

Your API key is stored in neocities-apikey. This file should be kept secure and never committed to public repositories.

You can get your API key from your Neocities dashboard at: https://neocities.org/settings

Features

• ✅ List files on your Neocities site
• ✅ Upload single files
• ✅ Upload multiple files at once
• ✅ Upload entire directories (with automatic batching)
• ✅ Delete files from your site
• ✅ Automatic rate limiting to avoid API abuse
• ✅ Progress indicators and emoji status updates

API Limits

According to Neocities API rules:

• Try to limit recurring site updates to one per minute
• Don't spam the server with tons of API requests
• The batch upload feature automatically handles rate limiting

Examples

Update your entire website:

python neocities-manager.py upload-dir ./website

Upload a new blog post:

python neocities-manager.py upload blog/2024-11-30-my-post.html blog/2024-11-30-my-post.html

Clean up old files:

python neocities-manager.py delete old-about.html deprecated-style.css

Check what file have on your site:

python neocities neocities-manager.py list

Troubleshooting

Permission errors

Make sure the neocities-apikey file is readable and contains your valid API key.

API errors

Check that your API key is valid and that you have permissions to perform the requested action.

Documentation

For full API documentation, visit: https://neocities.org/api