Getting Started

This page takes you from nothing to a working Phel project: a live REPL, a file you wrote, and a project layout you understand.

Requirements#

• PHP 8.5+ (php -v)
• Composer (composer --version)

No PHP on your machine, or you want the PHAR, Docker, or Nix? See Installation.

Create a project#

composer create-project --stability dev phel-lang/cli-skeleton example-app
cd example-app

The skeleton is a small CLI app with tests and Composer scripts already wired.

Open 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/
├── composer.json       ; PHP deps + phel scripts
├── phel-config.php     ; project config (main namespace, build output)
├── src/
│   ├── main.phel       ; entry namespace, run by composer dev
│   ├── commands/       ; CLI commands
│   └── core/           ; pure logic the commands call
└── tests/
    ├── commands/
    └── core/

Every command runs as vendor/bin/phel <cmd>. The skeleton adds Composer shortcuts:

See CLI Commands for every command and Configuration for phel-config.php.

Verify your setup#

vendor/bin/phel doctor

It checks the PHP extensions Phel needs, your source and test directories, OPcache, and the cache size. Run composer test to confirm the skeleton's tests pass.

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.