Install the CLI

neo is neosource’s command-line client. You do not need it — everything in Getting started works with plain git and the web UI. It exists for the things a browser is bad at: claiming and reading issues, opening pull requests, running a workflow locally before you push, and turning your own machine into a CI runner.

Install

macOS and Linux

curl -LsSf https://get.neosource.dev | sh

Installs to ~/.local/bin and adds it to your PATH if it isn’t already there. Override the location with NEO_INSTALL_DIR=/somewhere/else.

Windows

powershell -c "irm https://get.neosource.dev/install.ps1 | iex"

Installs to %LOCALAPPDATA%\Programs\neo and updates your user PATH.

Read it before you run it

Piping a script into your shell means trusting whatever it contains, and you should not take our word for it. Both scripts are served as plain text so they open directly in your browser:

• View install.sh
• View install.ps1

They are short and dependency-free. In full, the Unix one:

1. works out your platform from uname;
2. downloads the matching archive and verifies its SHA-256, refusing to install if it does not match;
3. copies neo into ~/.local/bin;
4. copies shell completions into completion directories only if they already exist — it will not create them;
5. writes a small receipt to ~/.local/share/neosource/;
6. if ~/.local/bin is not on your PATH, writes an env script there and appends one line sourcing it to ~/.profile, ~/.bashrc and ~/.zshrc — guarded so re-running never duplicates it.

It never uses sudo and writes nothing outside your home directory. Step 6 is the only thing that touches files you did not ask about; if you would rather it did not, set NEO_INSTALL_DIR to somewhere already on your PATH.

Prefer to inspect the exact bytes you will run? Download first, then execute:

curl -LsSf https://get.neosource.dev/install.sh -o neo-install.sh
less neo-install.sh
sh neo-install.sh

Then check it worked:

neo version
neo doctor

neo doctor is the one to run when something is off — it reports what neo can and cannot reach on this machine, including whether your login and token still work.

Sign in

neo auth login

This approves the login in a browser and stores a token in ~/.config/neosource/config.json.

Supported platforms

Platform	Architectures
macOS	Apple Silicon (arm64) and Intel (x86_64)
Linux	x86_64 and aarch64 — static, no glibc requirement
Windows	x86_64

Manual download

The installer resolves the right build from /dl/latest.json, which lists every artifact for the current release with its SHA-256 and size. To install by hand, take the URL for your platform from there, unpack it, and put neo somewhere on your PATH.

Each archive contains the binary, shell completions, and the licence.

Verifying a download

Every release publishes a SHA256SUMS next to its artifacts, and the same digests appear in latest.json. The install script checks them for you; if you downloaded by hand:

sha256sum -c SHA256SUMS

A note on OS warnings

Downloading with curl does not mark a file as quarantined on macOS, so the install command above runs without a Gatekeeper prompt. If you download an archive in a browser instead, macOS quarantines it and you will need to right-click → Open the first time.

On Windows, SmartScreen may warn about an unrecognised app, because the binary is not code-signed. Choose More info → Run anyway.

Shell completions

The installer copies completion files into the standard directories if they already exist; it will not create a shell’s completion tree on its behalf. Otherwise generate them at runtime — see Shell completions.

Updating and removing

To update, re-run the install command; it overwrites in place.

To remove neo:

rm ~/.local/bin/neo
rm -rf ~/.local/share/neosource ~/.config/neosource

What it can do

• neo auth login — sign in; neo token manages personal access tokens.
• neo issue / neo pr — list, view, claim and comment without a browser.
• neo run — run a workflow file from .neosource/workflows/ locally, in a container, before you push. See How CI works.
• neo push / neo adopt / neo migrate — create a repository from a checkout you already have, including bulk-adopting a directory of them.
• neo runner — register this machine as a self-hosted runner. The agent is built into neo, so there is nothing extra to install; see Runners.

Run neo <command> --help for the full surface.