> ## Documentation Index
> Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# Migrate from Photon CLI 1.0

> What changes when you install Photon CLI 3.0 over 1.0, and how to keep using 1.0.

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](https://docs.photon.codes/docs/beta/cli/installation.md#install-a-standalone-binary) 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](https://docs.photon.codes/docs/beta/cli/installation.md#photon-version-shows-an-older-version-than-you-installed)
shows how to find every copy and which command removes it. Then check with:

```sh theme={null}
photon --version
```

## 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`:

```sh theme={null}
npm install --global @photon-ai/cli@legacy
npx @photon-ai/cli@legacy spectrum lines list
```

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](https://github.com/photon-hq/cli/releases/tag/v2.3.0). The
[Photon CLI 1.0 installation](https://docs.photon.codes/docs/legacy/cli/installation.md) 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:

```text theme={null}
$ photon spectrum lines list
Error: "photon spectrum" is a Photon CLI 1.0 command. (LEGACY_COMMAND)
Next: Use Photon CLI 1.0: npx @photon-ai/cli@legacy spectrum lines list
Docs: https://photon.codes/docs/cli/output#errors
```

## 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](https://docs.photon.codes/docs/beta/cli/authentication.md).

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:

```text theme={null}
$ PHOTON_TOKEN=... photon project list
Error: PHOTON_TOKEN is a Photon CLI 1.0 credential, which this CLI does not read. (LEGACY_TOKEN)
Next:
  1. Use Photon CLI 1.0: npx @photon-ai/cli@legacy project list
  2. To use photon instead, unset PHOTON_TOKEN.
Docs: https://photon.codes/docs/cli/output#errors
```

### 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](https://docs.photon.codes/docs/beta/cli/projects/api-keys.md) (`pho_sk_...`),
and automation that must act as your account uses an
[account service key](https://docs.photon.codes/docs/beta/cli/service-keys.md) (`pho_ask_...`). See
[which credential to use](https://docs.photon.codes/docs/beta/cli/authentication.md#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.