Skip to main content
Install Photon CLI with npm, pnpm, Yarn, or Bun, or as a standalone binary for macOS, Linux, or Windows. A package install runs on Node.js 22 or newer, and Node must be on your PATH whichever package manager installs the CLI. The standalone binary needs no Node.js.
Coming from Photon CLI 1.0? Installing this CLI replaces 1.0’s photon command. See Migrate from Photon CLI 1.0 first.

Install with a package manager

Bun works as the package manager, but Node.js remains the supported runtime. pnpm 11 and later, and Yarn 4.12 and later, install a version only once it has been on npm for a day. On a release’s first day, they install the newest version that is at least a day old. To install a release on its first day, name its version. pnpm installs a version you name unless you set minimumReleaseAge yourself. Yarn also needs --no-time-gate:

Install a standalone binary

The installer downloads the newest release from GitHub, checks its SHA-256 checksum, and installs photon in ~/.local/bin, or in $XDG_BIN_HOME when that is set on macOS and Linux. A download that fails the check installs nothing. The installer prints the binary’s full path and adds its folder to your PATH when it isn’t there yet.
Open a new terminal so it picks up the new PATH, then run photon --version. On Alpine Linux, install the C++ runtime libraries before you run the installer. Without them, the installer still reports success, but photon exits with code 127 and Error loading shared library libstdc++.so.6:
On macOS and Linux, the installer adds the folder to PATH in ~/.profile; in ~/.bashrc and ~/.bash_profile when they exist; in ~/.zshrc when zsh is your shell or that file exists; and in fish’s conf.d when fish is your shell or its configuration folder exists. On Windows, it adds the folder to your user PATH. These environment variables change what the installer does:

Windows and Smart App Control

photon.exe is not code-signed. Windows SmartScreen may warn you the first time it runs. If Smart App Control is on, Windows blocks the binary, and Smart App Control has no way to allow a single app. On a PC with Smart App Control on, install with npm instead. The npm package runs on Node.js, which is signed:

Update

photon update updates a global npm, pnpm, Yarn, or Bun install with the same package manager, and replaces a binary the installer installed. For npx, a project dependency, or an install it doesn’t recognize, it prints the command to run and changes nothing. It never runs sudo. photon update --check only reports whether a newer version exists. At a terminal, the CLI checks for a new version once a day and shows a notice on standard error. To turn the notice off, set PHOTON_NO_UPDATE_NOTIFIER=1.

Verify the install

With Yarn, the CLI is a project dependency: run these, and every photon command in these guides, as yarn photon from the project folder.

Troubleshooting

photon --version shows an older version than you installed

Either the package manager installed an older version, or another, older photon runs instead of the one you installed. pnpm and Yarn wait a day before installing a release. pnpm 11 and later, and Yarn 4.12 and later, install a version only once it has been on npm for a day. On a release’s first day, they install the newest version that is at least a day old. Install again the next day: pnpm add --global @photon-ai/cli, or yarn up @photon-ai/cli in your project. To install it today, name the version, as Install with a package manager shows. npm and Bun don’t wait by default. Another photon runs first. Your shell runs the first photon it finds on your PATH. Bash and zsh also remember where they found a command, and keep running that copy after you install a new one.
  1. List every photon in the order the shell tries them. The first one runs.
    To see which version a copy is, run its path with --version, for example ~/.bun/bin/photon --version. In PowerShell, use & '<path>' --version. If no copy is the version you installed, the folder your package manager puts commands in isn’t on your PATH. Add it before you remove anything. pnpm bin --global and bun pm bin --global print that folder. For npm, it is the bin folder inside npm prefix --global, or that folder itself on Windows.
  2. Remove each older copy with the tool that installed it. On macOS and Linux, ls -l <path> also shows where a path links to. Use the first row whose text appears in the path or its link, ignoring case: Node.js version managers such as nvm and Vite+ keep npm’s global packages separately for each Node.js version, so switching versions can change which copy runs. If the path or its link names a Node.js version you aren’t using, switch to that version (for example, nvm use 22), run the npm command, then switch back and run the install command again.
  3. Run hash -r in bash or zsh, or open a new terminal, so the shell looks for photon again. Then run photon --version.

Next steps

Authentication

Sign in with photon login and check your session.

Projects

Pick an active project and start working.

Shell completion

Turn on Tab completion for photon commands.