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.


In short, my version offers the following features:


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:

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.


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