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

# Installation

> Install Photon CLI 1.0 via npm, or as a standalone binary

> [!NOTE]
>
> This page installs Photon CLI 1.0, the CLI for Spectrum. Its commands name npm's `legacy` tag, which stays on 1.0, so they never install a later major version.

## One-off — no install

You can run any CLI command on demand without a global install:

```sh npx theme={null}
npx @photon-ai/cli@legacy login
npx @photon-ai/cli@legacy projects ls
```

```sh pnpm dlx theme={null}
pnpm --package=@photon-ai/cli@legacy dlx photon login
pnpm --package=@photon-ai/cli@legacy dlx photon projects ls
```

```sh yarn dlx theme={null}
# Yarn Berry / v2+ only
yarn dlx @photon-ai/cli@legacy login
yarn dlx @photon-ai/cli@legacy projects ls
```

```sh bunx theme={null}
bunx @photon-ai/cli@legacy login
bunx @photon-ai/cli@legacy projects ls
```

Each time you run it, it pulls the newest 1.0 release automatically. This is useful for scripts, throwaway machines, or trying the CLI before committing.

## Global install

For daily use, you can install globally so `photon` is always on your `PATH`:

```sh npm theme={null}
npm install -g @photon-ai/cli@legacy
```

```sh pnpm theme={null}
pnpm add -g @photon-ai/cli@legacy
```

```sh yarn theme={null}
yarn global add @photon-ai/cli@legacy
```

```sh bun theme={null}
bun add -g @photon-ai/cli@legacy
```

```sh theme={null}
photon login
```

The `pho` shortcut alias is created automatically the first time you run `photon`.

> [!NOTE]
>
> You need Node.js 20.12 or newer to run the CLI. You can also use Bun, but it's not required.

## Standalone binary

If you don't want any runtime dependency (e.g. CI environments), you can download a prebuilt binary directly. Replace `<os>` and `<arch>` with your platform:

```sh theme={null}
# <os>: darwin | linux
# <arch>: arm64 | x64
curl -L -o /usr/local/bin/photon \
  https://github.com/photon-hq/cli/releases/download/v2.3.0/photon-<os>-<arch>
chmod +x /usr/local/bin/photon
photon --version
```

For example, on an Apple Silicon Mac:

```sh theme={null}
curl -L -o /usr/local/bin/photon \
  https://github.com/photon-hq/cli/releases/download/v2.3.0/photon-darwin-arm64
chmod +x /usr/local/bin/photon
```

Available platforms:

| Platform | Architectures |
| - | - |
| macOS | arm64, x64 |
| Linux | arm64, x64 |

Each binary ships with a corresponding `.sha256` checksum on the [release page](https://github.com/photon-hq/cli/releases/tag/v2.3.0).

## Update

The CLI shows a notification when a new version is available. To update:

```sh npm theme={null}
npm install -g @photon-ai/cli@legacy
```

```sh pnpm theme={null}
pnpm add -g @photon-ai/cli@legacy
```

```sh yarn theme={null}
yarn global add @photon-ai/cli@legacy
```

```sh bun theme={null}
bun add -g @photon-ai/cli@legacy
```

If you installed via a standalone binary, download it again from the `v2.3.0` release:

```sh theme={null}
curl -L -o /usr/local/bin/photon \
  https://github.com/photon-hq/cli/releases/download/v2.3.0/photon-<os>-<arch>
chmod +x /usr/local/bin/photon
```

If you use a one-off runner (`npx` / `pnpm dlx` / `yarn dlx` / `bunx`), you automatically pick up new 1.0 releases — no manual update needed. These tools cache resolved versions, so to force the newest 1.0 release immediately, name the `legacy` tag:

```sh theme={null}
npx @photon-ai/cli@legacy projects ls
```

> [!NOTE]
>
> To suppress the update notification, set `PHOTON_NO_UPDATE_NOTIFIER=1`.

## Verify the installation

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

`photon ping` hits the Photon API health endpoint — if you see a success response, you're ready to [authenticate](https://docs.photon.codes/docs/legacy/cli/authentication.md).


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