Photon Initialization: Complete Setup Guide

The photon init command suite configures your system for optimal Photon usage with shell integration, tab completion, and daemon auto-start.

Quick Setup

bash

# One-command setup: shell integration + daemon auto-start
eval "$(photon init all)"

After this, photons work as direct commands immediately:

bash

list add "Buy milk"          # instead of: photon cli list add "Buy milk"
kanban board                 # instead of: photon cli kanban board
photon use todo shopping-list

Commands Overview

Command	Purpose
`photon init cli`	Shell integration + completion cache setup
`photon init daemon`	Auto-start daemon on login
`photon init all`	Run both `cli` and `daemon`
`photon init completions`	Show/regenerate completion cache
`photon uninit cli`	Remove shell integration
`photon uninit daemon`	Remove daemon auto-start

`photon init cli` — Shell Integration

Sets up your shell to run photons as direct commands with full tab completion.

What It Does

bash

photon init cli

This command:

Detects your shell — zsh, bash, or PowerShell (auto-detection via $SHELL or Windows platform)
Adds shell hook — Appends a single eval/invoke line to your rc file
Generates completion cache — Creates ~/.photon/.data/.cache/completions.cache with all photon metadata
Creates shell functions — Generates one function per installed photon (e.g., list(), kanban())
Sets up fallback handler — New photons work immediately without shell restart

Installation

bash

# Auto-detects shell, updates rc file, and activates integration
eval "$(photon init cli)"       # zsh/bash
# or
Invoke-Expression (& photon init cli)  # PowerShell

Supported Shells

Shell	Profile	Completion	Hook
zsh	`~/.zshrc`	`compdef` + `_arguments`	`eval "$(photon init cli)"`
bash	`~/.bashrc`	`complete -F` + `compgen`	`eval "$(photon init cli)"`
PowerShell	`$PROFILE`	`Register-ArgumentCompleter`	`Invoke-Expression (& photon init cli)`

Shell Detection

Auto-detection works via:

zsh/bash — $SHELL environment variable
PowerShell — $PSModulePath or Windows platform

If detection fails, set $SHELL explicitly:

bash

SHELL=/bin/zsh photon init cli

What Gets Installed

The hook creates three things in your shell:

1. Shell Functions (for direct invocation)

bash

# After init, these functions are created for each photon:
list() { photon cli list "$@"; }
kanban() { photon cli kanban "$@"; }
git-box() { photon cli git-box "$@"; }

2. Tab Completion (reads from cache)

bash

# Tab completion cache at ~/.photon/.data/.cache/completions.cache
# Contains: photon names, methods, parameters, instances
# Updated when `photon init cli` runs or when you add new photons

3. Fallback Handler (for new photons before shell restart)

bash

# zsh: command_not_found_handler()
# bash: command_not_found_handle()
# Falls back to: photon cli "$@" if file exists

Internal Completion Initialization

Key point: photon init cli automatically initializes the completion cache.

typescript

// From init.ts lines 418-426:
const { CACHE_FILE } = await import('../../shell-completions.js');
try {
  await fs.access(CACHE_FILE);
} catch {
  // Cache doesn't exist yet — generate it
  const { generateCompletionCache } = await import('../../shell-completions.js');
  await generateCompletionCache();
}

This means:

✅ First run of photon init cli automatically generates completions
✅ You don't need to run photon init completions --generate separately
✅ Completion cache is always up-to-date after setup

Tab Completion Examples

After setup, tab completion works at multiple levels:

bash

# Photon name completion
lis⇥         → list (from ~/ .photon/cache/completions.cache)

# Method completion
list ⇥       → add, get, remove (methods of list photon)

# Parameter completion
list add --⇥ → --item, --priority (parameters of list.add)

# Instance completion
photon use list ⇥  → shopping-list, groceries (named instances)

# Full photon command
photon cli ⇥        → list, kanban, git-box (installed photons)
photon cli list ⇥   → add, get, remove (methods)

`photon init daemon` — Auto-Start on Login

Registers Photon daemon to start automatically when you log in.

What It Does

bash

photon init daemon

Creates a platform-specific auto-start entry:

macOS — launchd plist in ~/Library/LaunchAgents/dev.photon.daemon.plist
Linux — systemd service in ~/.config/systemd/user/photon-daemon.service
Windows — Task Scheduler entry PhotonDaemon

The daemon:

Starts automatically at login
Persists photon state across sessions
Broadcasts state changes to multiple connected clients
Enables real-time sync across CLI, Beam UI, and Claude Desktop

Platform-Specific Setup

macOS (launchd)

bash

photon init daemon

# Start it now without logging out:
launchctl load ~/Library/LaunchAgents/dev.photon.daemon.plist

# Check if it's running:
launchctl list | grep photon

# View logs:
tail -f ~/.photon/daemon-init.log

Linux (systemd)

bash

photon init daemon

# Enable and start the service:
systemctl --user enable photon-daemon
systemctl --user start photon-daemon

# Check status:
systemctl --user status photon-daemon

# View logs:
journalctl --user -u photon-daemon -f

# Note: Requires lingering enabled
loginctl enable-linger

Windows (Task Scheduler)

powershell

photon init daemon

# Verify in Task Scheduler:
Get-ScheduledTask -TaskName "PhotonDaemon"

# Start it now:
Start-ScheduledTask -TaskName "PhotonDaemon"

`photon init all` — Complete Setup

Runs all setup steps in sequence: shell integration + daemon auto-start.

What It Does

bash

photon init all

Equivalent to:

bash

photon init cli     # Install shell integration + cache
photon init daemon  # Register daemon auto-start

Output

Setting up Photon...

Step 1/2: Shell integration
  ✓ Installed shell integration into /Users/arul/.zshrc

    Type any photon name directly:
      list get
      list add "Milk"
    Tab completion is enabled for: Photon names, methods, parameters, and instances.

Step 2/2: Daemon auto-start
  ✓ Daemon auto-start registered: /Users/arul/Library/LaunchAgents/dev.photon.daemon.plist
    The daemon will start automatically at next login.
    To start it now without logging out:
      launchctl load /Users/arul/Library/LaunchAgents/dev.photon.daemon.plist

✓ Photon setup complete.

`photon init completions` — Completion Cache Management

Manages the shell completion cache at ~/.photon/.data/.cache/completions.cache.

Show Cache Status

bash

photon init completions

# Output:
Cache: /Users/arul/.photon/cache/completions.cache
  Last updated: 2h ago
  Run `photon init completions --generate` to refresh

Regenerate Cache

bash

photon init completions --generate

# Output:
✓ Completions cache updated: /Users/arul/.photon/cache/completions.cache

When to Regenerate

The cache is automatically generated by photon init cli. Manually regenerate if:

You installed new photons and they're not in completions
You modified a photon's methods/parameters
The cache became corrupted

Cache Contents

The cache file contains one entry per line:

photon:list:List management
photon:kanban:Kanban board
method:list:add:Add an item
method:list:get:Get all items
param:list:add:--item:string:true
param:list:add:--priority:choice:false
instance:list:shopping-list
instance:list:groceries

Format: type:name:description or type:photon:method:name:description

`photon uninit cli` — Remove Shell Integration

Removes the shell hook and completion setup.

What It Does

bash

photon uninit cli

Removes from your rc file:

Eval/invoke line for the hook
Old shell hook references (migrations from previous versions)
Comments and markers

After Removal

bash

# Run to apply changes
exec $SHELL    # zsh/bash
. $PROFILE     # PowerShell

# Or restart your terminal

Important

Removes only the integration line — doesn't delete:

~/.photon/ directory
~/.photon/.data/.cache/completions.cache
Any photon data or state

`photon uninit daemon` — Remove Auto-Start

Removes daemon auto-start registration.

macOS

bash

photon uninit daemon

# Unloads and removes:
launchctl unload ~/Library/LaunchAgents/dev.photon.daemon.plist
rm ~/Library/LaunchAgents/dev.photon.daemon.plist

Linux

bash

photon uninit daemon

# Disables and removes:
systemctl --user disable photon-daemon
rm ~/.config/systemd/user/photon-daemon.service

Windows

powershell

photon uninit daemon

# Removes Task Scheduler entry:
schtasks /delete /tn "PhotonDaemon" /f

Setup Architecture

Phase 1: Shell Integration (`photon init cli`)

photon init cli
    ↓
[Shell Detection]
    ├─ $SHELL env var → zsh/bash
    ├─ $PSModulePath → PowerShell
    └─ Windows platform → PowerShell
    ↓
[Generate Hook Script]
    ├─ Shell functions for each photon
    ├─ Tab completion logic
    └─ Fallback handler for new photons
    ↓
[Install to RC File]
    ├─ ~/.zshrc  (zsh)
    ├─ ~/.bashrc (bash)
    └─ $PROFILE  (PowerShell)
    ↓
[Generate Completion Cache]
    └─ ~/.photon/.data/.cache/completions.cache
       (Contains: photons, methods, params, instances)
    ↓
eval hook emitted to stdout (captured by eval wrapper)
    ↓
✓ Direct photon invocation works
✓ Tab completion enabled

Phase 2: Daemon Auto-Start (`photon init daemon`)

photon init daemon
    ↓
[Detect Platform]
    ├─ macOS → launchd plist
    ├─ Linux → systemd service
    └─ Windows → Task Scheduler
    ↓
[Resolve photon binary]
    └─ Uses `which photon` or `where photon`
    ↓
[Create Auto-Start Entry]
    ├─ Command: photon daemon start
    └─ Startup trigger: Login / system boot
    ↓
[Log location]
    └─ ~/.photon/daemon-init.log (macOS/Linux)
    ↓
✓ Daemon starts automatically at next login
✓ State persisted and shared across clients

Phase 3: Full Setup (`photon init all`)

photon init all
    ↓
    ├─ Run: photon init cli (step 1/2)
    │   └─ Shell integration + completion cache
    │
    └─ Run: photon init daemon (step 2/2)
        └─ Auto-start registration
    ↓
✓ Both phases complete

Troubleshooting

Shell Integration Not Working

Symptom: Photons still require photon cli prefix

Fixes:

bash

# 1. Verify hook was installed
cat ~/.zshrc | grep "photon init cli"

# 2. Re-run setup and activate
eval "$(photon init cli)"

# 3. Check functions exist
declare -f list  # should show function definition

Tab Completion Not Working

Symptom: No suggestions when pressing TAB

Fixes:

bash

# 1. Check cache file exists
ls -la ~/.photon/.data/.cache/completions.cache

# 2. Regenerate cache
photon init completions --generate

# 3. Activate shell integration (if not already done)
eval "$(photon init cli)"

Daemon Not Starting

Symptom: photon daemon doesn't respond

Fixes (macOS):

bash

# 1. Check plist is loaded
launchctl list | grep photon

# 2. Manually load plist
launchctl load ~/Library/LaunchAgents/dev.photon.daemon.plist

# 3. Check for errors
tail -f ~/.photon/daemon-init.log

Fixes (Linux):

bash

# 1. Check service status
systemctl --user status photon-daemon

# 2. Enable lingering (if needed)
loginctl enable-linger

# 3. Check logs
journalctl --user -u photon-daemon -n 50

Shell Detection Fails

Symptom: "Unsupported shell: fish"

Fix:

bash

# Set $SHELL explicitly
SHELL=/bin/zsh photon init cli

Verification Checklist

After running photon init all:

[ ] Shell hook installed in rc file (~/.zshrc, ~/.bashrc, or $PROFILE)
[ ] Completion cache created at ~/.photon/.data/.cache/completions.cache
[ ] Shell restarted or sourced (eval line activated)
[ ] Photon name works directly without photon cli prefix (e.g., list add)
[ ] Tab completion works (try: list ⇥)
[ ] Daemon auto-start registered (check platform-specific location)
[ ] Daemon can be started manually (macOS: launchctl load ..., Linux: systemctl --user start ...)

Shell Integration — Detailed tab completion reference
Getting Started — First-time setup guide
Daemon Architecture — How the daemon works internally

Photon Initialization: Complete Setup Guide ​

Quick Setup ​

Commands Overview ​

photon init cli — Shell Integration ​

What It Does ​

Installation ​

Supported Shells ​

Shell Detection ​

What Gets Installed ​

Internal Completion Initialization ​

Tab Completion Examples ​

photon init daemon — Auto-Start on Login ​

What It Does ​

Platform-Specific Setup ​

macOS (launchd) ​

Linux (systemd) ​

Windows (Task Scheduler) ​

photon init all — Complete Setup ​

What It Does ​

Output ​

photon init completions — Completion Cache Management ​

Show Cache Status ​

Regenerate Cache ​

When to Regenerate ​

Cache Contents ​

photon uninit cli — Remove Shell Integration ​

What It Does ​

After Removal ​

Important ​

photon uninit daemon — Remove Auto-Start ​

macOS ​

Linux ​

Windows ​

Setup Architecture ​

Phase 1: Shell Integration (photon init cli) ​

Phase 2: Daemon Auto-Start (photon init daemon) ​

Phase 3: Full Setup (photon init all) ​

Troubleshooting ​

Shell Integration Not Working ​

Tab Completion Not Working ​

Daemon Not Starting ​

Shell Detection Fails ​

Verification Checklist ​

Related Guides ​

Photon Initialization: Complete Setup Guide

Quick Setup

Commands Overview

`photon init cli` — Shell Integration

What It Does

Installation

Supported Shells

Shell Detection

What Gets Installed

Internal Completion Initialization

Tab Completion Examples

`photon init daemon` — Auto-Start on Login

What It Does

Platform-Specific Setup

macOS (launchd)

Linux (systemd)

Windows (Task Scheduler)

`photon init all` — Complete Setup

What It Does

Output

`photon init completions` — Completion Cache Management

Show Cache Status

Regenerate Cache

When to Regenerate

Cache Contents

`photon uninit cli` — Remove Shell Integration

What It Does

After Removal

Important

`photon uninit daemon` — Remove Auto-Start

macOS

Linux

Windows

Setup Architecture

Phase 1: Shell Integration (`photon init cli`)

Phase 2: Daemon Auto-Start (`photon init daemon`)

Phase 3: Full Setup (`photon init all`)

Troubleshooting

Shell Integration Not Working

Tab Completion Not Working

Daemon Not Starting

Shell Detection Fails

Verification Checklist

Related Guides