Skip to content

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 | sh

When it runs, the script does the following in order.

  1. Checks for Node 22 or later and npm. If either is missing or too old, it stops and tells you how to install it.
  2. Downloads the latest Phillip release info (latest.json) and the .tgz package from Tara.
  3. Compares the package's sha256 with the value Tara publishes. If they don't match, it doesn't install.
  4. Runs npm install -g with that package.
  5. Checks whether npm's bin directory is on PATH, and warns if the ph command on the machine points to a different program.
  6. 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:

bash
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 environment

If 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 systemInstall commandUser configuration is stored in
macOS, Linuxcurl -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:

bash
npm install -g ./phillip-<version>.tgz

This 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.

  1. Open a new terminal, because the shell rereads its configuration only at startup.

  2. See which directory to add:

    bash
    echo "$(npm prefix -g)/bin"
  3. Add that directory to PATH. For example, with zsh:

    bash
    echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

    For Bash, use ~/.bashrc on Linux or ~/.bash_profile on macOS. On Windows, add the directory that npm prefix -g prints to your user Path variable, then reopen PowerShell.

  4. Run ph --version to 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:

bash
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

On 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:

bash
npm uninstall -g @phillipcli/phillip

If 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:

bash
curl -fsSLo phillip-vscode.vsix https://tara.phillipcli.cloud/phillip/phillip-vscode-latest.vsix
code --install-extension phillip-vscode.vsix

If 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.

LineMeaning
✗ Node, ✗ Claude Code, ✗ git, ✗ TaraRequired. Fix it and run again
⚠ Ryoma, ⚠ Collector, ⚠ GuardrailsOptional, with a suggested fix

The environment passes when no ✗ line remains. A ⚠ line doesn't block you. For other errors, see Troubleshooting.

Read more ​