Installation

palm is a Node.js command-line tool published to npm as @paliontech/palm. The package installs one command, palm.

npm install -g @paliontech/palm
palm --version

The first command installs palm for your user. The second prints the installed version.

Requirements

Requirement	Why
Node.js 22 or later	palm declares Node 22 as its minimum in `package.json`.
git	palm fetches every source with the `git` on your `PATH`.
macOS or Linux	palm is tested on both. On Windows, run palm inside WSL.

Private repositories need the git credentials you already use, such as an SSH key or a credential helper. palm never prompts for a password, so a missing credential fails with a hint instead of hanging.

Run palm inside WSL

palm 0.2 does not run on native Windows. A maintainer on Windows installs Node 22, git and palm inside WSL, and runs palm there.

wsl
npm install -g @paliontech/palm

Keep the repository in the WSL file system, such as ~/src/<repo>, so git and palm see the same line endings. palm writes text files with LF line endings. Contributors who only use the harnesses need no palm at all: the generated files are committed, and each harness reads them on Windows as it does elsewhere. Native Windows support stays on the list for palm 1.0.

Other package managers

pnpm add -g @paliontech/palm
bun add -g @paliontech/palm

To try palm without installing it, run it through npx.

npx @paliontech/palm --help

Check the installation

palm --help lists the eight verbs on one screen. Inside a project that already uses palm, palm check runs every consistency check and changes nothing.

palm --help
palm check

Shell completion

palm completion prints a completion script for bash, zsh or fish.

echo 'source <(palm completion zsh)' >> ~/.zshrc

Replace zsh with bash and ~/.zshrc with ~/.bashrc for bash. For fish, write the script to ~/.config/fish/completions/palm.fish.

Upgrade

npm install -g @paliontech/palm@latest

palm does not check for updates and never updates itself. A newer palm may render an entity differently. The next palm install then reports it as ~ re-rendered, and palm check fails until you commit the result. For that reason, pin the exact version in CI, such as npm install -g @paliontech/palm@0.2.0, and upgrade it in a pull request of its own.

From palm 0.1

palm 0.2 reads a new palm.yaml format and version 3 of palm.lock.yaml. Every command except palm migrate stops on the old files and names that command.

palm migrate --dry-run
palm migrate

Migrate from palm 0.1 walks through it, including the global scope. palm migrate ships with 0.2 only, so run it before you upgrade to 0.3.

Uninstall

npm uninstall -g @paliontech/palm

This removes the command only. Files palm generated in your projects are committed there and stay, and they keep working without palm. Run palm get in a project, and palm get -g, to see what palm installed before you remove it.

palm keeps its own state in ~/.palm.

Path	Holds
`palm.yaml`, `palm.lock.yaml`	The global scope’s manifest and lock. You may keep these in a dotfiles repository.
`applied.yaml`	What the global scope wrote on this machine, with real paths.
`assets/`	Scripts that global hooks and MCP servers run.
`kit/`	The in-repo source `palm create -g` writes to. You may keep it in a dotfiles repository too.
`cache/`	Checkouts and indexes. Safe to delete.

Delete ~/.palm to remove that state.