Neocities Management Script

Published: 2021/09/11

Last updated: 2021/09/11

One of the things that initially intrigued me about Neocities was the promise of a dedicated CLI program for managing one’s site. Neocities provided this in the form of a Ruby gem, but I wasn’t happy with it. It didn’t work quite the way I wanted it to work, and worse, in recent times it seems to have inexplicably broken. I don’t know Ruby. I do, however, know Perl, and I saw that no one had yet written a Perl-based Neocities client. Clearly, it fell to me to do so.

So I did.

Overview

In short, my version offers the following features:

• Site statistics for either the logged-in site or any given site by username (e.g. “shadowm00n” would display my site’s statistics).
• Directory listings, either of a given directory or recursively of the entire site, with an optional detailed mode showing file sizes and modification times. Specific filetypes are highlighted in different colours, similar to the GNU version of ls(1).
• File deletion, uploads, and pushing, all with optional dry-runs.
  • Deletion supports (optionally case-insensitive) regular expressions.
  • Uploading is for specific groups of files, and can optionally preserve all paths relative to the local PWD and/or put files into specific folders irrespective of the local PWD.
    • The PWD, or “Present Working Directory”, is the directory you are in when a program is launched.
  • Pushing is a convenience feature for essentially uploading or updating significant chunks of a site with the assumption that the included files directly mirror the remote site; optionally, regex is supported for selecting the files to upload, and this regex can optionally be case-insensitive.
  • Both forms of uploading additionally support a “face” option, which ensures that the given HTML file is uploaded last, to accomodate Neocities’ social media feature, which shows the most recent HTML update as the “face” of the posting. This is primarily to accomodate any use of wildcards or recursion, and the script does not otherwise alter the order of filenames given to it.
  • Both forms of uploading won’t upload stuff that already exists and has the same SHA1 hash on the remote server.

Installation

Currently, installing it is a little bit of work, as it requires several outside dependencies. Also, currently this script is only explicitly supported under GNU/Linux. It probably works on a *BSD system, and might work on a Windows system under Strawberry Perl or the like, but it is entirely untested at this point.

The libraries needed, along with their Debian/Ubuntu package names, are as follows:

• Config::Simple (libconfig-simple-perl)
• JSON (libjson-perl)
• LWP::UserAgent (libwww-perl)
• Term::ReadKey (libterm-readkey-perl)
• Text::Table (libtext-table-perl)

In one easily-copyable command, that would be:

sudo apt install libconfig-simple-perl libjson-perl libwww-perl libterm-readkey-perl libtext-table-perl

That’s about it. If your distro of choice is somehow missing one of those packages, you’ll need to invoke the cpan(1) program manually, e.g.:

cpan -i Config::Simple

Once that’s accomplished, and the script itself saved somewhere in your $PATH, you’ll need to log in, which is done via the “login” sub-command. It will prompt you for your Neocities account name and password, the latter of which is not echoed to your screen, intentionally. Just keep typing. Once your account has been verified, the configuration file will store only your account name and a unique API key which is effectively the same as the password, so don’t put it anywhere public.

Usage

This is a fairly complex program, so you’re best off reading the provided help and manual, which can be invoked via the “help” and “man” sub-commands respectively. The most important takeaway is that your PWD matters. Always launch the script from precisely where you mean to, which is almost always the root of your project directory. Examples are provided in the manual to clarify this. I don’t wish to republish the entire thing here, but please do make sure to read it.

Concluding Thoughts

Admittedly, I kind of wrote this one for me and my own usage, and I’ve been sitting on it for months at the time of publishing. Part of this is because I’m always a little scared to release things, part is because I wanted to test it “just a little more”, and part is because I was unsure if anyone else would even care. I finally decided to tie up some loose ends and release it after someone on IRC found it helpful. I hope others can find a good use for it too.

If you find any flaws, or if you find it useful, please feel free to let me know.

Back to main page