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
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 installsphoton 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.
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:
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
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.
-
List every
photonin 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 yourPATH. Add it before you remove anything.pnpm bin --globalandbun pm bin --globalprint that folder. For npm, it is thebinfolder insidenpm prefix --global, or that folder itself on Windows. -
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. -
Run
hash -rin bash or zsh, or open a new terminal, so the shell looks forphotonagain. Then runphoton --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.