<< Go back to Posts

Neocli - Updating your Neocities website efficiently

Neocities has a GUI to update your website. Unfortunately, it is buggy, especially when you have nested repository. They have an API, but it was incomplete. I builded a tool to update my website simply. Here, I describe the main necessary commands.



Introduction

My static website is hosted on neocities. It is free up to 1Go, which is more than enough for a personal use.

The main marketed goal of neocities is “educative”, to discover how to build a website. However, it does not seem to address professional use cases.

My main concern was about updating my website:

  • you have a Graphical User Interface (GUI), which is not very convenient when you want to update 10 files, plus there are some bugs (try a drag and drop with nested folders)
  • You also have a Command Line Interface (CLI), but many “basic” functions are missing. You can only update / delete one file after another, which is very time consuming.

As the official CLI was written in Ruby, and I did not want to learn this language just for one project, I decided to write a new one using python.

» Source Code on GitHub «

It does not require any particular libraries, and you don’t need to do any lib installation. It just need a chmod +x neocli.py, and you are almost done.

It is limited to Linux only (I use / and not \), but you can upgrade the code to become platform agnostic.

Table of content

Commands

Info

A neocities website has some metadata.

There is one command to get info:

./neocli.py info japoneris
== Get website info ==
{
  "result": "success",
  "info": {
    "sitename": "japoneris",
    "views": 68885,
    "hits": 132456,
    "created_at": "Sat, 21 Jan 2017 11:30:27 -0000",
    "last_updated": "Wed, 21 Jun 2023 11:50:47 -0000",
    "domain": null,
    "tags": [
      "programming",
      "technology",
      "art",
      "science",
      "diy"
    ],
    "latest_ipfs_hash": null
  }
}

This is all the info you get from the profile page

Getting your API Key

To use neocities API, you need to have your API_KEY.

Or you can find it on your profile, or you can use the script to log in and get the key.

./neocli.py auth
== Authentication ==
Input username (lowercase):
Input password:

If the authentication is successful, the API key will be stored in the API_KEY.txt file.

If you have several website, rename this file to distinguish your different keys.

Testing your API KEY

If you want to verify that the key is working, list the documents/folders:

./neocli list

It will return all files/folder located at the root.

  • If you want all the files/folder: /neocli.py list --rec
  • If you want all the files/folder under a given directory: ./neocli.py list --path=book --rec

There are boolean options to get files only or folders only.

You can ask for metadata such as size or last modification date.

Updating Everything

This is my favorite command. It update the whole website, taking into account all the changes (new files and modification).

Note: It does not delete any file.

The command first makes a diff between local and remote files. Then, it pushes all documents that have been updated (or new).

This comparison is done by using the remote hashes (returned by the API), which are compared to the local hashes.

./neocli.py opti <my_local_website_path>

The <website path> must be the root folder. If you use jekyll, this is my/path/to/_site/

If you want a preview of what will be updated, you can add the flag --debug: Nothing would happen. You will have printed the changes (new files and updated files).

Updating one Part

You may want to push several files / folder to a particular location:

./neocli.py path/to/docs*.html --remote_path="book/2022/"

The selected documents will be pushed into the directory book/2022/

Deleting Stuff

The command is similar to the update command.

./neocli.py delete <remote_path_to_file_or_folder_to_be_destroyed>

Code

If you want to try this tool, click here to access the GitHub repository.



>> You can subscribe to my mailing list here for a monthly update. <<