This page takes you from an empty folder to a running Phel project. You create the project with Composer, try code in the REPL, run a file, and see where each part of the project lives.
Requirements
- PHP 8.5+ (
php -v) - Composer (
composer --version)
No PHP on your machine? Quick launch runs Phel with one command. For the PHAR, Docker, or Nix, see Installation.
Create a project
composer create-project --stability dev phel-lang/cli-skeleton example-app
cd example-appOpen the REPL
composer repl
You should see:
Welcome to the Phel Repl (v0.54.0)
Type (exit) or press Ctrl-D to exit.
user:1>
Try a few expressions:
user:1> (+ 1 2 3)
6
user:2> (def xs [1 2 3])
#'user/xs
user:3> (conj xs 4)
[1 2 3 4]
user:4> xs
[1 2 3] ; original vector is unchanged
user:5> (map inc xs)
(2 3 4) ; map returns a lazy sequence
user:6> (php/date "Y-m-d") ; call any PHP function
"2026-04-21"
Exit with Ctrl+D or (exit). The REPL guide covers history, introspection, and debug helpers.
Write your first file
Create src/hello.phel:
(ns cli-skeleton.hello)
(defn greet [name]
(str "Hello, " name "!"))
(println (greet "Phel"))
Run it:
vendor/bin/phel run src/hello.phel
# Hello, Phel!
The ns form names the namespace. Every file starts with one. The skeleton's own entry point runs with composer dev.
Project layout
example-app/
├── phel-config.php ; project config (main namespace, build output)
├── src/main.phel ; entry namespace, run by composer dev
└── tests/ ; run by composer test
Every command runs as vendor/bin/phel <cmd>. The skeleton adds Composer shortcuts:
| Script | Runs |
|---|---|
composer repl | phel repl |
composer dev | phel run cli-skeleton.main |
composer test | phel test |
composer build | phel build, compiles to plain PHP |
composer format | phel format |
See CLI Commands for every command and Configuration for phel-config.php.
Next steps
- Practice: First Steps: short graded exercises you solve in the REPL.
- Basic Types: every literal and how it maps to PHP.
- Build a Web App: a complete guestbook, end to end.