Neocities

Directory uploads
Upload a directory, including the output of your static site generator.
Skip unchanged files
Only new and changed files are uploaded.
.gitignore support
Skip files listed in the upload directory's root .gitignore.

Getting started

Install the CLI

With Ruby installed, open your terminal and run:
```
$ gem install neocities
```
Ruby installation
Set up your API key

Open Settings, choose your site, and find API key. Create or copy your key, then run:
```
~/mywebsite $ neocities info

Please enter your Neocities API key.
Create or copy one from https://neocities.org/settings
API key: ****************
```
Paste your key at the prompt. The CLI saves it on your computer for future commands and shows your site's information.

Keep your API key secret. It grants access to your site files.
Upload your site

From the directory containing your site's files, run:
```
~/mywebsite $ neocities push .

Uploading index.html ... SUCCESS
Uploading style.css ... EXISTS
Uploading cat.jpg ... SUCCESS
```
EXISTS means the file already matches the one on your site, so the CLI skips uploading it.

For a generated site, upload the build directory. For example, Jekyll uses _site:
```
~/mywebsite $ neocities push _site
```
Push uploads new and changed files. Files already on your site are kept unless you use --prune.

Commands

Preview an upload

A dry run shows what would be uploaded without changing your site.

~/mywebsite $ neocities push --dry-run .

Doing a dry run, not actually pushing anything
Uploading index.html ... SUCCESS
Uploading style.css ... EXISTS

Upload files

Upload individual files, or choose a destination directory on your site.

# Upload files to the root of your site
~/mywebsite $ neocities upload index.html style.css

# Put an image in the images directory
~/mywebsite $ neocities upload -d images cat.jpg

List files

List all the files and directories on your Neocities site.

~/mywebsite $ neocities list -a

images
images/cat.jpg
index.html
style.css

Delete files and log out

Delete a remote file, then remove the saved API key from this computer.

~/mywebsite $ neocities delete old.html
Deleting old.html ...
SUCCESS: file(s) have been deleted

~/mywebsite $ neocities logout -y
Your API key has been removed.

Logging out only removes the saved key. To revoke it everywhere, regenerate it in your site settings.

Command help

Run the CLI without arguments for the command list. Add help and a command name to see its options.

$ neocities

  |\---/|
  | o_o |   Neocities 
   \_-_/

Subcommands:
  push        Recursively upload a local directory to your site
  upload      Upload individual files to your Neocities site
  list        List files from your Neocities site
  ...

$ neocities help push

Automation

Set NEOCITIES_API_KEY in your environment to run commands without a prompt. The CLI uses this key instead of any saved key and does not save it locally.

For CI, add the key to your provider's secret store and expose it as NEOCITIES_API_KEY. Then run your build and upload the output:

# NEOCITIES_API_KEY is supplied by your CI environment
~/mywebsite $ neocities push _site

Uploading index.html ... SUCCESS
Uploading style.css ... SUCCESS

Replace _site with your build's output directory. Keep API keys out of your source files and Git repository.

Git hooks

Complete the API key setup once, or set NEOCITIES_API_KEY in your environment. Then add the following to .git/hooks/pre-push in your repository:

#!/bin/sh
neocities push .

Make the hook executable:

~/mywebsite $ chmod u+x .git/hooks/pre-push

If you already have a pre-push hook, add the upload command to it. For a generated site, replace . with your output directory, such as _site, and run your build before pushing.

Neocities CLI

Getting started

Install the CLI

Set up your API key

Upload your site