Core workflow
Build & lifecycle
Turn source code into a managed process, then control its complete runtime lifecycle.
Build an application
phelix build compiles the project in the current directory (auto-detects Go or Rust), starts it on the given port, and records a new versioned build. A Build Report with regression analysis is printed automatically after every successful build - see Build reports.
phelix build myapp -p 8080 --tag "v1.2.3"NAME and --port are resolved in this order: CLI argument/flag, then phelix.yaml, then the default 8080, then an interactive prompt. When the config file supplies both, the command runs without asking anything.
| Flag | Default | Purpose |
|---|---|---|
| --port, -p | 8080 | Port to run the app on (matrix builds never start an instance, so no port is required) |
| --build-arg, -a | - | Extra args passed to the build tool (repeatable); in matrix mode they are passed to every go build / cross build |
| --tag | - | Human label stored with the version (e.g. "hotfix-auth") |
| --no-upload | false | Don't sync app info to the server |
| --debug | false | Verbose build/tool output |
| --matrix | false | Matrix mode: build versions x platforms (also activated by the phelix.yaml matrix profile) |
| --go-versions | - | Go versions, e.g. 1.22,1.23,1.27 |
| --rust-versions | - | Rust versions, e.g. 1.77,1.78.2 |
| --platforms | - | Targets, e.g. linux/amd64,linux/arm64 |
| --matrix-concurrency | 3 | Max parallel matrix builds |
| --matrix-retries | 0 | Retry failed matrix combinations up to N additional times (transient failures only) |
| --resume | - | Resume an interrupted matrix run (implies matrix mode) |
| --matrix-dry-run | false | Print the plan without building |
Rebuild after changes
phelix rebuild rebuilds an existing app from its source directory. Without an argument, the app is taken from phelix.yaml (name:) when it exists in the current directory, otherwise an interactive picker is shown.
phelix rebuild myapp --blue-greenphelix rebuild myapp --replicas 3 # Canary: 5% of traffic, verified, then promotedphelix rebuild myapp --canary 5 # One-off override: deploy classic once, even though phelix.yaml says rollingphelix rebuild myapp --strategy classic # Rolling once; replica count comes from deploy.replicas, else 1phelix rebuild myapp --strategy rolling| Flag | Default | Purpose |
|---|---|---|
| --port, -p | previous / 8080 | Port to run on |
| --build-arg, -a | - | Extra build args (repeatable) |
| --tag | - | Version label |
| --no-upload | false | Skip server sync |
| --strategy | - | Strategy for this rebuild only: classic, blue-green, rolling, canary, or progressive. Overrides phelix.yaml; never written back to it |
| --blue-green | false | Zero-downtime blue-green deploy (needs phelix proxy) |
| --replicas | 0 | Zero-downtime rolling deploy over N replicas |
| --canary | 0 | Canary deploy: route N percent (1-99) of traffic to the new version, verify health and metrics, then promote. Verification window and thresholds come from phelix.yaml deploy.rollout (needs phelix proxy and an existing deployment) |
| --auto-rollback | false | On a deploy-phase failure (instance start, health check, traffic switch), automatically restore the previous known-good version. Build/compile failures never trigger it |
| --source-dir | app directory | Compile from another source directory, as used by webhook worktrees. App identity, output binary, ports, and deployment state stay with the app; phelix.yaml and the recorded Git commit come from the source directory. |
The deployment path is resolved in this order: explicit --blue-green / --replicas, then --strategy, then the config's deploy.strategy, then the strategy the app is currently deployed with, then classic. An app already running blue-green or rolling therefore stays on it unless a classic rebuild is asked for explicitly; a rolling rebuild inherited this way keeps the replica count the app is running at. Both zero-downtime modes and canary rollouts auto-start the proxy daemon if it is not already running. The deployment paths are documented in Deployment strategies, Zero-downtime deploys, and Canary & progressive rollouts.
Lifecycle commands
| Command | Behavior |
|---|---|
| phelix build <NAME> | Compile, version, and start a Go or Rust project. |
| phelix rebuild <NAME> | Rebuild an existing app with classic or zero-downtime deployment. |
| phelix start [<NAME>] | Start one app, or every app when no name is supplied. --ensure builds if missing. |
| phelix stop <NAME> | Stop a running app. |
| phelix restart <NAME> | Restart an app. |
| phelix status <NAME> | Show PID, uptime, RAM/CPU, watching, version, deploy mode, and proxy routing. |
| phelix list | Table of every managed app with version, status, watching, deploy, and proxy columns. |
| phelix log [<NAME>] | Tail app logs (last 10 lines + live stream); no arg shows Phelix's own logs. |
| phelix remove <NAME> | Stop and remove an app from management. |
| phelix watch <NAME> | Enable (default) or disable backend monitoring for one app (--disable). |
phelix start accepts --ensure: it builds the app if it is missing and rebuilds it if startup fails. phelix status shows PID, uptime, RAM/CPU, the watching state, the active version, deploy mode, and proxy routing for the app. phelix watch toggles per-app backend monitoring - see Per-app watching.