Skip to main content

Getting Started

2 min read Last updated
On this page

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-app

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/
├── 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:

ScriptRuns
composer replphel repl
composer devphel run cli-skeleton.main
composer testphel test
composer buildphel build, compiles to plain PHP
composer formatphel format

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

Next steps