Installation
This page covers how to install Phillip on each operating system, how to fix PATH, how to upgrade and uninstall, and how to install the VS Code extension. If you need the path from the beginning to your first task, see Dev and Test.
What your machine needs
You need Node 22 or later with npm (check with node --version), git, and one of three operating systems: macOS, Linux, or Windows. You also need write access to npm's global install directory, because the install script doesn't use sudo (see npm install directory). Finally, you need your organization's Tara address, which this documentation writes as https://tara.phillipcli.cloud. Ask your team lead or the operations team for the real address.
Install from Tara
Tara serves the install script and has already written its own address into the script. The script doesn't go through any external package service.
curl -fsSL https://tara.phillipcli.cloud/install.sh | shWhen it runs, the script does the following in order.
- Checks for Node 22 or later and
npm. If either is missing or too old, it stops and tells you how to install it. - Downloads the latest Phillip release info (
latest.json) and the.tgzpackage from Tara. - Compares the package's sha256 with the value Tara publishes. If they don't match, it doesn't install.
- Runs
npm install -gwith that package. - Checks whether npm's
bindirectory is onPATH, and warns if thephcommand on the machine points to a different program. - Writes the Tara address and Tara's public key into Phillip's user configuration, leaving the other keys in the configuration unchanged.
After installing, verify and set up like this:
ph --version # the Phillip version, then the bundled Claude Code version
ph setup # sign in to Tara, choose a harness, connect GitHub/GitLab, check the machine (run in a repo directory)
ph forge doctor # check the environmentIf you belong to more than one organization, ph setup (through ph login) asks which one to use. In CI, pass it explicitly with ph login --org acme or set PHILLIP_ORG=acme. Switch later with ph org switch <slug>. A person with no organization yet creates one on the Portal's Get started screen or with ph org create <slug>.
Install commands by operating system
| Operating system | Install command | User configuration is stored in |
|---|---|---|
| macOS, Linux | curl -fsSL https://tara.phillipcli.cloud/install.sh | sh | ~/.config/phillip/config.json (or under XDG_CONFIG_HOME) |
| Windows (PowerShell) | irm https://tara.phillipcli.cloud/install.ps1 | iex | %APPDATA%\phillip\config.json |
To change the configuration directory, set the PHILLIP_HOME environment variable before you run the script. If the machine has no curl, the script uses wget. On Windows, if Node isn't installed, the script suggests running winget install OpenJS.NodeJS.
Install with npm
If your team lead gives you a .tgz package file, or you don't want to use the script, install it directly:
npm install -g ./phillip-<version>.tgzThis way doesn't write the Tara address into the configuration. So in the setup step, run ph setup --tara https://tara.phillipcli.cloud so that Phillip fetches the address and public key.
Add to PATH
ph and phillip are two names for the same program, located in npm's bin directory. If the terminal reports ph: command not found, that directory isn't on PATH.
Open a new terminal, because the shell rereads its configuration only at startup.
See which directory to add:
bashecho "$(npm prefix -g)/bin"Add that directory to
PATH. For example, with zsh:bashecho 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrcFor Bash, use
~/.bashrcon Linux or~/.bash_profileon macOS. On Windows, add the directory thatnpm prefix -gprints to your userPathvariable, then reopen PowerShell.Run
ph --versionto verify.
If the machine has another program also named ph, the install script warns you. In that case, use phillip instead of ph, or move npm's bin directory earlier in PATH.
npm install directory
An EACCES error means npm is installing into a system directory that you can't write to. Don't use sudo npm. Have npm install into your own directory instead:
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrcOn Windows, run npm config set prefix "$env:APPDATA\npm" and then add that directory to Path. Then run the install command again.
Upgrade and uninstall
To upgrade, run the same install command again. The script fetches the latest release from Tara, verifies the sha256, and installs over the old one, and your configuration and sign-in stay as they are. Bandum running on your machine is upgraded separately with ph bandum ui upgrade, and resources in a project use ph tara outdated and then ph tara upgrade.
To uninstall, run:
npm uninstall -g @phillipcli/phillipIf you also want to delete the configuration and data, first sign out with ph tara logout to revoke the session and remove the token from the machine, then delete the configuration directory listed in the table above. If your organization installed Guardrails on the machine with administrator rights, uninstall it by following the operations team's instructions, because ph guardrails uninstall needs sudo.
Install the VS Code extension
The Phillip extension for VS Code is a .vsix file that Tara serves next to the Phillip package. Download it and install it with these commands:
curl -fsSLo phillip-vscode.vsix https://tara.phillipcli.cloud/phillip/phillip-vscode-latest.vsix
code --install-extension phillip-vscode.vsixIf your Tara requires sign-in for downloads, sign in on the Tara page first and open the same address in the browser to save the file.
Or in VS Code, open Extensions, click the ... menu, and choose Install from VSIX.... The extension doesn't keep its own token. It runs the ph command for you, so you need to install Phillip and sign in first. See also VS Code extension.
Reading the ph forge doctor result
ph forge doctor tells you whether the environment is complete.
| Line | Meaning |
|---|---|
✗ Node, ✗ Claude Code, ✗ git, ✗ Tara | Required. Fix it and run again |
⚠ Ryoma, ⚠ Collector, ⚠ Guardrails | Optional, with a suggested fix |
The environment passes when no ✗ line remains. A ⚠ line doesn't block you. For other errors, see Troubleshooting.