Docs › Getting started › Installation

Installation

This page walks you through installing the tool on your machine. Most people only need the first method below. If you are running on a server or inside a container, skip to Deployment notes.

Requirements

Before you begin, make sure your system meets the following minimum requirements.

Component	Minimum	Recommended
Operating system	macOS 12, Ubuntu 20.04, Windows 10	Latest LTS release
Memory	2 GB	4 GB or more
Disk space	300 MB	1 GB
Runtime	Node.js 18	Node.js 20 or 22

Install with a package manager

The quickest way to get started is to install the published package globally using your package manager of choice.

npm pnpm yarn Homebrew

npm install --global example-tool

Once the command finishes, confirm the installation worked by checking the version:

example-tool --version

You should see output similar to the following:

example-tool 4.2.1

Install from source

If you want the latest development build or plan to contribute, clone the repository and build it locally.

git clone https://github.com/example/example-tool.git
cd example-tool
npm install
npm run build
npm link

The npm link step makes the example-tool command available on your path, pointing at your local checkout.

Note: Source builds can change between commits. If you run into problems, check out the latest tagged release with git checkout v4.2.1 before building.

Verify the installation

Run the built-in self check. It validates your runtime, checks file permissions and confirms that the tool can reach its default configuration directory.

example-tool doctor

A healthy installation prints a short summary with no errors:

✔ Runtime       Node.js 20.11.0
✔ Permissions   ~/.config/example-tool is writable
✔ Network       registry reachable
All checks passed.

Troubleshooting

Command not found after installing

Your global package directory is probably not on your PATH. Print the directory npm uses for global binaries and add it to your shell profile:

npm config get prefix
export PATH="$(npm config get prefix)/bin:$PATH"

Permission denied during install

Avoid using sudo with npm. Instead, configure a user-owned global prefix as described in your package manager's documentation, then run the install again without elevated privileges.

Unsupported Node.js version

The tool requires Node.js 18 or newer. Check your version with node --version. If it is older, install a current release with a version manager such as nvm or fnm.

Heads up: On Windows, run your terminal as a regular user rather than as Administrator. Elevated shells can install the tool to a location that other user accounts cannot access.

Deployment notes

For servers and CI environments, you can skip the global install and pin the version in your project instead:

npm install --save-dev example-tool@4.2.1
npx example-tool --version

Pinning a version keeps builds reproducible. See the deployment guide for container images, environment variables and health checks.