trans-neptunian object

an unofficial guide to the neocities CLI

intro

if you’re like me and you have way too much time on your hands, you might already know that neocities has developed a command-line interface (CLI) for using their API, which makes it easier than ever to manage your very own Personal Webbed Site. and if you’re like me, then you might also:

prefer editing files in a more robust text editor on your computer, rather than using the janky web version;
hate having to resort to such inelegant solutions as dragging and dropping files into the dashboard, manually renaming folders, deleting unnecessary files, etc.; but
you only have a passing knowledge of computers and struggle to parse the official documentation for the aforementioned CLI (which is kind of ass imo).

(also assuming you aren’t a paying supporter of neocities, and as such can’t host the files directly from your computer.)

so if that all sounds like you, then!! well!!! cool? i don’t actually know that anyone wants or needs this guide, but when i was screwing around trying to find a workable solution, i couldn’t find any resources that were both useful and understandable to my computer-illiterate ass. so now that i have the knowledge, i figured i may as well put it up for anyone else who’s interested in doing the same.

but also be careful in making changes to your computer and use your best judgement and all that.

ok now for the actual tutorial

materials needed:

computer (with admin privileges)
neocities account
the bravery to traverse strange and unknown lands (aka the command line)

step 1: install ruby

what is ruby?

Ruby is an interpreted, high-level, general-purpose programming language. It was designed with an emphasis on programming productivity and simplicity. In Ruby, everything is an object, including primitive data types. It was developed in the mid-1990s by Yukihiro “Matz” Matsumoto in Japan.

- Ruby (programming language) - Wikipedia

the neocities module is written in this language.

windows

download the latest version of ruby installer from rubyinstaller.org and use it to install ruby.

linux

you can use a package manager (if you use linux, i assume you don’t need me to explain what that is) or select from a list of installers.

macOS

sorry but you’re shit out of luck man, i don’t have a mac

nah but there’s also installers for macOS. but you’re on your own from here. google it. idk.

disclaimer: i use windows 10. the entire guide will be written specifically with that in mind, but if you’re willing to do a bit of research, you should be able to adapt the instructions to whatever OS you’re on.

step 2: install the neocities CLI module

what’s a module, anyway?

a term you might not be familiar with in this context is module. (you probably technically don’t need to know what that is, so you can keep scrolling cough cough)

anyway. there’s these things called modules – you might also see terms like library or package, and in ruby they’re called gems. they’re all referring to the same thing, more or less: a script or set of scripts used to avoid having to write everything out yourself, potentially multiple times.

imagine you’re trying to directly access the neocities API with node.js. here’s an example, taken directly from that page:

var neocities = require('neocities')
var api = new neocities('YOURUSERNAME', 'YOURPASSWORD')

api.delete(['img1.jpg', 'img2.jpg'], function(resp) {
  console.log(resp)
})

do you want to write this out every time you delete a file? fuck no!!!

this is what the module is for: someone else has already defined all the functions for uploading, downloading, deleting, etc., so that you can call each one by name. simply entering neocities delete img1.jpg img2.jpg will yield the same end result, reducing 6 lines to 1. (but we’re not there yet.)

(i’m not 100% sure this is how it works, i’m not an expert on programming but i think it’s a good definition for right now ok?)

for more information, see this wikipedia page on loadable kernel modules.

first, open the command prompt in administrator mode. on windows 10, you can do this by right-clicking the windows icon in the bottom left and selecting Command Prompt (Admin).

now enter this command:

gem install neocities

if there’s no issues, something like this should appear in the command prompt:

Successfully installed neocities-0.0.20
Parsing documentation for neocities-0.0.20
Done installing documentation for neocities after 1 seconds
1 gem installed

to test that the module is properly installed and working, try the command neocities version, and it should respond with the version number.

0.0.20

step 3: configuring the module

but before you can upload any files, you have to log in. use the command neocities info; the module should ask for your username and password, which you’ll have to type in manually.

after logging in, the command will run normally.

C:\Users\REDACTED>neocities info
Please login to get your API key:
sitename: trans-neptunian-object
password: REDACTED
The api key for trans-neptunian-object has been stored in C:\Users\REDACTED\AppData\Local/neocities/config.json.
sitename     trans-neptunian-object
views        17191
hits         32698
created_at   2022-09-28 14:12:50 +0800
last_updated 2024-09-06 22:59:30 +0800
domain
tags         ["personal", "writing"]

but isn’t that dangerous??

you might be a little cagey about giving your login info to this program, and rightly so. however, the module does not actually store your username and password. it instead uses these to retrieve the API key for your site, which is what allows you to upload new files and access existing ones from the command line, without having to verify your credentials every single time.

but if you really don’t want to enter your information, there’s another option: manually adding your API key to the module’s configuration, which is located at C:\Users\YOURUSERNAME\AppData\Local\neocities\config.json. edit the contents of the file, subsituting in your own API key and site name:

{"API_KEY":"YOURAPIKEY","SITENAME":"YOURSITENAME"}

you can find your API key by going to your website settings (https://neocities.org/settings/YOURSITENAME#api_key).

(i haven’t actually tried this but i assume it works. lol)

keep in mind that if you share your API key with another person, they will have the ability to edit your site or delete everything.

ok i promise we’re done with the setup now. sorry for all the bold text. but this is the kinda shit you have have to keep in mind when you're messing with the command line......

step 4: using the module

if you don’t already have the files on your computer, you can get them by going to your neocities dashboard and scrolling down to the link that says Download Entire Site. you’ll get a zip file with the name of your website: unzip it and place the contents wherever’s best for you. for example, i have mine in C:\Users\REDACTED\Documents\neocities\trans-neptunian-object.

and now that you have the files on your computer you can use another text editor, instead of the terrible, terrible web version! 💖 (and i’d recommend keeping a local backup of your site, in any case.)

ok, back to the command prompt. you might've noticed before, but the text in front of all the commands you're typing in should read C:\WINDOWS\system32> (or C:\Users\YOURUSERNAME> if you’re not in administrator mode, which you should be), which is the directory you’re currently running commands in. you’ll have to switch to the folder where you placed all the files for your site in order to make use of them; use this command to do so:

cd C:\PATH\TO\YOUR\SITE

and the prefix thingy will change: C:\PATH\TO\YOUR\SITE>

using the cd command

cd changes the current directory (aka folder) that you’re working from. it’s the same idea as going to your Pictures folder to send someone an image, for example, except that the way you get there is through typing a command, rather than using the file explorer.

note: if any part of your path contains a space in one of the folder names, e.g. C:\Users\YOURUSERNAME\Documents\neocities\my website, you’ll have to wrap it in quotes, like so:

cd "C:\Users\YOURUSERNAME\Documents\neocities\my website"

or else it won’t work.

although it’s generally considered best practice to not use spaces to begin with.

now you can use the module! upload a file or something! just like with the web editor, you’ll have to do a hard refresh to see the changes in your browser.

commands

both the documentation and the module itself offer an explanation of all the commands, so i’ll just provide a couple to help you get started.

command	result
`neocities`	brings up a list of all the commands
`neocities COMMANDNAME`	explains the given command (try `neocities push`)
`neocities push .`	uploads all files in the current directory
`neocities upload FILENAME`	uploads specified file(s)

extras

yeah i’m still yapping

examples

i don’t know if having an exclusively text-based tutorial made things confusing, so i’m including some examples as well.

here’s a truncated excerpt of my file hierarchy:

Documents
  neocities
    trans-neptunian-object
      about
        - credits.html
        - index.html
      images
        bg
          - stars.gif
      - index.html
      - style.css

(items preceded by a dash are files, and the rest are folders.)

when i’m using the module to manage my site, i’ll navigate to the directory with cd C:\Users\REDACTED\Documents\neocities\trans-neptunian-object. this means the folder named trans-neptunian-object is now the root directory. if i run the command neocities push ., it will upload all files and folders in this directory (i.e., every item under trans-neptunian-object in the excerpt).

if i wanted to only upload credits.html to my site, i would do neocities upload misc/credits.html. since the file itself isn’t located in the root directory, i have to append the misc/ to indicate the folder it’s in. (and remember, the note about having spaces in your file or folder names still applies.)

* there are more notes i could add about using upload and push but then i'd just be rehashing the pre-existing documentation so. read that instead

oh yeah and you can use tab completion so you don’t have to type out the whole file name.

using .gitignore

(link to official documentation)

git itself is a whole other beast, but in this context, all you need to know is that a .gitignore file is a list of all the files and folders you don’t want to upload.

for example, if you’re in the middle of completely rewriting your CSS, you might not want to update the CSS on the live version until you’re done. or maybe you have a screenshot or something in that folder that you don’t want to be uploaded either. iunno.

to do this, you have to create a file in your root directory called .gitignore. yes, exactly like that: no name preceding the file extension. you can create an empty .txt file and rename it, and then open it in notepad or whatever.

so all you do is write in the names of the files you don’t want to include in your uploads, like so:

index.html
style.css

images/bg/stars.gif

the upload will not include index.html, style.css, or stars.gif.

if you want to override a line without deleting it from the file, you can add a # in front of it:

# index.html
# style.css

images/bg/stars.gif

the upload will not include stars.gif. it will include index.html and style.css.

i honestly might make a tutorial for using git specifically for neocities at some point – it’s a fucking nightmare to figure out, but it’s worth the headache, imho.

the end

that’s all! congratulations on getting to the end! i know using the command line can be a confusing hellscape when you’re first starting out, but what it lacks in comfort and convenience, it makes up for by streamlining your process.

as i said before, i wanted to make this guide so people could have something a little more beginner-friendly (well, relatively speaking, y’know) available, as i guess it’s a pretty specific niche. although i’m not sure how anyone’s going to find it. but anyway i hope this was helpful, if a bit rambling at times.

have fun with your fancy new CLI tools! don’t forget to like and subscribe