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

# Shell completion

> Turn on Tab completion for photon commands in zsh, bash, fish, and PowerShell.

`photon complete <shell>` prints a completion script for zsh, bash, fish, or
PowerShell. Load the script in your shell, and Tab completes photon's commands:
`photon pro` completes to `photon project`, and `photon project cr` to
`photon project create`. The steps on this page were run with Photon CLI 3.0.2.

No install method turns completion on. The npm package has no install scripts,
and the standalone installers only add photon's folder to your `PATH`. Add the
lines for your shell yourself, then open a new terminal.

## zsh

Add these lines to `~/.zshrc`:

```zsh ~/.zshrc theme={null}
autoload -Uz compinit && compinit
source <(photon complete zsh)
```

The first line starts zsh's completion system, which the script needs. If your
`~/.zshrc` already runs `compinit`, add only the second line, after it. When
`compinit` hasn't run before the `source` line, a new terminal prints
`command not found: compdef`, and Tab doesn't complete photon's commands.

To save the script to a file instead, write it to a folder in zsh's `fpath`,
and add that folder to `fpath` before `compinit` runs:

```zsh theme={null}
mkdir -p ~/.zfunc
photon complete zsh > ~/.zfunc/_photon
```

```zsh ~/.zshrc theme={null}
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit
```

A saved script runs photon from the path it had when you saved the script.
Save it again when you move photon or reinstall it another way. The `source`
line makes a new script in every new terminal, so it doesn't need this.

## bash

Add this line to `~/.bashrc`:

```bash ~/.bashrc theme={null}
source <(photon complete bash)
```

The script needs the bash-completion package, loaded before this line. Ubuntu's
default `~/.bashrc` loads it. Without it, Tab prints
`bash: _get_comp_words_by_ref: command not found`.

bash reads `~/.bashrc` when a terminal starts a non-login shell. A login shell
reads the first of `~/.bash_profile`, `~/.bash_login`, and `~/.profile` that
exists instead. If your terminal starts login shells, have that file source
`~/.bashrc`.

To save the script to a file instead, write it to bash-completion's folder for
your own completions. bash-completion loads it the first time you press Tab
after `photon`:

```bash theme={null}
mkdir -p ~/.local/share/bash-completion/completions
photon complete bash > ~/.local/share/bash-completion/completions/photon
```

That folder is `$BASH_COMPLETION_USER_DIR/completions` when you set
`BASH_COMPLETION_USER_DIR`. Otherwise, when you set `XDG_DATA_HOME`, it's
`$XDG_DATA_HOME/bash-completion/completions`.

## fish

Save the script to fish's completions folder. fish loads it the first time you
press Tab after `photon`:

```fish theme={null}
mkdir -p ~/.config/fish/completions
photon complete fish > ~/.config/fish/completions/photon.fish
```

The folder is `$XDG_CONFIG_HOME/fish/completions` when you set
`XDG_CONFIG_HOME`.

## PowerShell

Add this line to your PowerShell profile, the file `$PROFILE` names:

```powershell $PROFILE theme={null}
photon complete powershell | Out-String | Invoke-Expression
```

## The pho command

The npm package also installs photon as `pho`. The scripts complete the
`photon` command only, so `pho pro` followed by Tab completes nothing.

## When the script isn't saved

The `source` lines for zsh, bash, and PowerShell save no file. The rest of this
section is about saved scripts.

The shell opens the file before photon runs. When the folder doesn't exist, the
shell reports `No such file or directory` and photon doesn't run, so create the
folder first, as the commands above do.

On a full disk, Photon CLI 3.0.2 doesn't always report that the script wasn't
saved:

| Install | No space left | Some space left, but not enough |
| - | - | - |
| Package (npm, pnpm, Yarn, or Bun), which runs on Node.js | photon prints `Error: Photon could not write the result to standard output. (OUTPUT_WRITE_FAILED)`, exits with code `1`, and leaves an empty file. | photon exits with code `0` and leaves the script cut off. |
| Standalone binary | photon prints nothing, exits with code `0`, and leaves an empty file. | photon exits with code `0` and leaves the script cut off. |

After a full disk, free some space and save the script again.

`photon complete` knows zsh, bash, fish, and powershell. For any other shell
name, such as a misspelled `fsh`, Photon CLI 3.0.2 prints nothing, exits with
code `0`, and leaves an empty file.

To check a saved script, compare it with a new one. This prints `saved` only
when the file holds the whole script, so an empty or cut-off file prints
nothing:

```sh theme={null}
photon complete fish | cmp -s - ~/.config/fish/completions/photon.fish && echo saved
```


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