Reference
Storage and error handling
Understand Phelix state on disk and how common failures are handled.
Storage layout
~/.phelix/
├── apps.json # registry of all managed apps
├── master.key # AES-256-GCM master key (0600)
├── session.json # auth session
├── config.json # server configuration
├── proxy.sock # proxy daemon control socket
├── logs/
│ ├── phelix.log # Phelix's own log
│ ├── <app>.log # per-app logs
│ └── deploy_*.log # deploy instance logs
├── registry/<slug>.enc # encrypted registry credentials
└── apps/<AppName>/
├── versions.json # version metadata index
├── deploy.json # blue-green / rolling state
├── rollback.log # rollback audit trail
├── current → builds/vN # symlink to the active build
├── builds/vN/binary # versioned binaries
└── env/vN.enc # per-version encrypted env snapshotRetention
The last five versions are kept by default. The active version is never pruned, even when it falls outside the configured window.
Error handling
Errors are rendered once, on stderr, with a short code, the message, and an actionable hint (for example phelix auth login for auth failures). Successful output stays on stdout and is never polluted with error text.
| Failure | Behavior |
|---|---|
| Authentication | Prompt to run phelix auth login |
| Build | Show the failing stage and a hint |
| Connection | Log and retry automatically |
| Server communication | Handle gracefully without crashing the CLI |
| Deployment health | Abort and keep serving the active version |
Root causes are always preserved: wrapped errors stay reachable through errors.Is / errors.As, so os.IsNotExist, exec.ExitError, and gRPC status codes still work on the underlying cause.
Debugging failures
Pass --debug to any command to render the full error chain — root cause included — on stderr. It never discloses secrets: every rendered string is run through secret redaction in both normal and debug mode.