Skip to main content
Photon CLI 1.0 is the CLI for Spectrum. It was published as @photon-ai/cli versions up to 2.3.0. Photon CLI 3.0 is the CLI for the Photon platform, and it is published under the same package name. npm’s latest tag points to 3.0, and its legacy tag stays on 1.0.

Installing 3.0 replaces 1.0

Both packages install the photon command and its pho alias. Installing 3.0 globally with the package manager that installed 1.0 replaces 1.0, so after npm install --global @photon-ai/cli, an npm install of 1.0 is gone and photon runs 3.0. If 1.0 came from another package manager or from a downloaded binary, it stays installed next to 3.0, and the folder that comes first in your PATH decides which photon runs. The standalone installer installs photon only, with no pho alias, so a pho left from 1.0 still runs 1.0. Remove the 1.0 copy you no longer want. Troubleshooting shows how to find every copy and which command removes it. Then check with:

Keep using 1.0

To put 1.0 back, install it from the legacy tag. To run one 1.0 command without installing it, use npx:
If you installed 1.0 with a package manager, photon update in 1.0 releases up to 2.2.0 installs 3.0, because those releases update to npm’s latest tag. 2.3.0 updates from the legacy tag and stays on 1.0. To keep 1.0, install 2.3.0 with the command above before you run photon update. 1.0’s standalone binaries for macOS and Linux are on the 2.3.0 release. The Photon CLI 1.0 installation page has every way to install 1.0. When you run a 1.0 command in 3.0, 3.0 doesn’t run it. It exits with code 2 and gives the same command through npx @photon-ai/cli@legacy as its next step:

What changed

Commands

These 1.0 commands aren’t in 3.0: billing, config, env, ping, profile, projects, and spectrum. Use 1.0 for Spectrum work. 3.0’s commands are account, auth, link, login, logout, operation, org, project, unlink, update, and whoami. Its photon project commands manage Photon projects, whose IDs start with pho_prj_. They don’t manage 1.0’s Spectrum projects. Run photon --help for the full list.

Sign-in

3.0 doesn’t use 1.0’s sign-in. Run photon login once after you install 3.0. 3.0 keeps its sign-in in your operating system’s credential manager, apart from 1.0’s, so signing in or out of one CLI doesn’t change the other. See Authentication. 3.0 doesn’t read 1.0’s PHOTON_TOKEN or DASHBOARD_TOKEN. When one of them is set and PHOTON_API_TOKEN isn’t, every command other than help and the version exits with code 2 and points to 1.0:

Keys

1.0 runs CI with PHOTON_TOKEN, the access token its device sign-in saves, and Spectrum apps use a project ID and secret. 3.0 uses Photon keys instead. In CI, put a service identity API key (pho_scred_...) in PHOTON_API_TOKEN. An app’s own calls use a project API key (pho_sk_...), and automation that must act as your account uses an account service key (pho_ask_...). See which credential to use.

Node.js

1.0’s package runs on Node.js 20.12 or newer. 3.0’s package needs Node.js 22 or newer. The 3.0 standalone binary needs no Node.js.