Repository navigation
Caligrafer Project Commands
The project commands of Caligrafer set a project
up and run its development server: quickstart, initialize, created, server, the shell launcher .bin/caligrafer,
and version. This page says what each one does, step by step, and what it prints.
/caligrafy-quill:idea and the Quickstart with Claude
run quickstart for you; /caligrafy-quill:server starts, stops or checks the Docker server, and looks for a port
another project already holds before it starts it.
/caligrafy-quill:server start
Check before you say OK: the address it prints opens the home page, and php caligrafer.php doctor has no FAIL.
In a fresh copy of the framework (composer create-project caligrafy/caligrafy-quill bookshelf, or a clone):
cd bookshelf
.bin/caligrafer quickstart --exampleWith Docker running, it installs the PHP libraries, starts the dev-box container, and runs
php caligrafer.php quickstart --example in it. Then open http://localhost:8080. The whole walk-through, with its
output, is the Quickstart.
quickstart [--example] [--yes]: sets up a fresh project in one step (database, framework tables, /capabilities and /mcp); --example adds the Tasks example. With Docker: .bin/caligrafer quickstart
| Option | Effect |
|---|---|
--example |
adds the Tasks example: its capabilities, a model, a page, the tasks table, its routes and public/js/capabilities.js
|
--yes |
allows the initialize step to delete the framework's .git
|
--url <address> |
the address of the project on a local server, when it is not in a known web folder |
--no-db |
skips the database steps |
--db-defaults |
without a terminal, uses the local server's MySQL defaults instead of skipping the database |
--docker, --local
|
.bin/caligrafer only: which server runs it (see below) |
Each step runs only when it is needed, so quickstart can be run again: it only does what is missing and never
overwrites a file.
-
initialize, whenapplication/does not exist yet (refused without--yeswhen a.gitfolder is there). - The database settings: with Docker,
DB_ACTIVATE=true,DB_HOST=mysqlandDB_DATABASE=caligrafyin.env; on a local server (MAMP, XAMPP, LAMP),APP_ROOTfrom the project's place in the web folder and the MySQL settings, asked with the server's defaults. - The database itself (
CREATE DATABASE IF NOT EXISTS) and the framework tables (platform install). A local MySQL that does not answer setsDB_ACTIVATE=falseagain. -
Route::capabilities('/capabilities'),Route::mcp('/mcp')andRoute::notifications()aboveRoute::run()inapplication/config/routing/web.php. - With
--example, the Tasks example.
The class behind it is Caligrafy\Quickstart.
initialize: Initializes and signs your project
php caligrafer.php initialize # APP_ROOT=<folder name>: the site is at http://localhost/<folder>/
php caligrafer.php initialize off # any word after initialize: APP_ROOT empty, the site is at the root (Docker)
php caligrafer.php initialize --yes # also deletes .git without askingPreparing and signing the project for usage...
Contributor skill removed (.claude/skills/caligrafy-contributor: for the framework repository only)
Claude Code plugin source: caligrafy-myapp-b6ea (enable caligrafy-quill@caligrafy-myapp-b6ea when Claude Code asks)
.git kept (php caligrafer.php initialize --yes deletes it)
Application initialized successfully
APP_KEY=...
API_KEY=...
What it does, in order:
-
The keys. It writes
APP_KEYandAPI_KEYat the top of.env. A project that already has both keeps them (Existing APP_KEY and API_KEY kept): new keys would revoke the API keys, sign everyone out and make encrypted data unreadable. -
APP_ROOT. Always rewritten: the folder's name, or empty when a word followsinitialize(.bin/caligraferaddsoffwhen no local Apache runs, because Docker serves the project at the root). -
The Vue SPA template. It writes
framework/librairies/app/.envwithVITE_API_ROUTE=and no key: that build is public. -
application/. When it does not exist, it copiesframework/settings/applicationthere and writesapplication/.caligrafy-manifest.json, whichupgradereads to tell your files from untouched copies. A failed copy printsInitialization failed: framework/settings/application could not be copied to ./application.and exits with1. -
Uploads.
public/uploadsis made writable (chmod -R 777). -
The contributor skill.
.claude/skills/caligrafy-contributoris for the framework's own repository: it is removed. -
The Claude Code plugin. The project's plugin source gets its own name (
caligrafy-<folder>-<4 hex>), so that Claude Code does not give every project the first one's plugin. -
.git. Deleted only with--yes, or aytyped at the question in a terminal:This folder has a .git folder (the framework's history, or your project's). Delete it so that your project starts its own history? [y/N]. Without a terminal (a script, Claude) and without--yes, it is kept.
Ask before
initialize --yesin a git repository. It deletes.git, and the history with it, unless it was pushed somewhere.
Composer runs it at the end of composer create-project caligrafy/caligrafy-quill <folder>; you never run it yourself.
It prints the folder, the one next command, and what it found on this computer:
Caligrafy Quill 2.25.0 is in /Users/me/www/bookshelf. One more command sets it up:
cd bookshelf
.bin/caligrafer quickstart --example
On Windows the command is php caligrafer.php quickstart --example. It then says the address when the folder is in the
web folder of a MAMP, XAMPP or LAMP server, that a running local server cannot see a folder outside its web folder, and
whether Docker is running (quickstart uses it, or add --docker to use it instead).
server <start | stop | rebuild>: Starts a Caligrafy local LAMP server with phpmyadmin (requires PHP, Composer and Docker); rebuild updates the server image
| Command | Runs |
|---|---|
server start |
docker compose up -d dev-box scheduler |
server stop |
docker compose stop |
server rebuild |
docker compose build --pull dev-box, then docker compose up -d dev-box scheduler
|
Caligrafy Server successfully started.
Hostname: http://localhost:8080
phpmyadmin: http://localhost:8077
mysql: localhost:3306 (from your computer; mysql:3306 from the containers)
mysql username: root
mysql password: root
-
The containers (
docker-compose.yaml):dev-box(the PHP image ofdocker/Dockerfile, your folder mounted at/var/www/html),scheduler(the same image, runningphp caligrafer.php schedule work),mysql(MySQL 8.4) andphpmyadmin(5.2.3). -
The ports it prints are the ones Docker published, so a
docker-compose.override.ymlthat moves them (another project holds 8080) is followed; when the containers are not running, it reads the compose files and their override (2.24.0). -
The first start builds the image and takes minutes; later starts take seconds. Run
rebuildafter a change todocker/Dockerfile, or to update the system packages. -
A local Apache. Through
.bin/caligrafer,servergets a last word:localwhen a local web server (MAMP, XAMPP, LAMP) runs, and then it only says that this server serves the project (turn it off to use Docker). Run by hand,php caligrafer.php server startalways uses Docker (2.24.0). -
When it fails:
The Docker server could not start: is Docker Desktop running? (or a port is taken: docker-compose.override.yml moves them), exit code1.
The shell launcher, for macOS and Linux:
.bin/caligrafer quickstart [--docker | --local] [quickstart options]
.bin/caligrafer <command> [options]-
quickstartchooses the server:--dockeror--local, else the local server when Apache (httpdorapache2) runs and PHP is installed, else Docker when it runs; with neither it says what to start. In a folder with a.gitand noapplication/it asks before going on (theinitializestep deletes.git) and adds--yeswhen you sayy. It installs the PHP libraries whenvendor/autoload.phpis missing (your Composer, else thecomposer:2image with Docker), startsdev-boxand runsphp caligrafer.php quickstartin it, or runs it with your PHP. Then it registers the project's Claude Code plugin when theclaudecommand is installed. -
Any other command, with PHP and Composer on the computer: it runs
./caligrafer.php <command>with your arguments as typed.initializeandserverget the word that says whether a local server runs. A folder withoutapplication/or.envonly acceptsinitialize,version,doctorandupdate, and otherwise printsThis folder is not a Caligrafy project yet (no application/ or .env): start it with .bin/caligrafer quickstart. -
Without PHP or Composer, it runs
.bin/server start|stop: theprod-boxcontainer, with the code copied into the image.
php caligrafer.php version # also --version and -vCaligrafy Quill 2.25.0
It is handled before anything else is loaded: it works before composer install and never creates .env. In code, the
version is Caligrafy\Framework::VERSION.
-
.gitgone after setting up (G25, G95):initializedeletes it only with--yesor a typedysince 2.9.2; before,.bin/caligraferraninitializeon its way to other commands and deleted it without asking. -
The ports clash with another project (G12):
server startfails. Adocker-compose.override.ymlremaps the host side ("8081:80","8078:80","3307:3306"), andserverthen prints the new ports. -
.envreplaces the Docker settings (G11):.envvalues win over theenvironmentofdocker-compose.yaml. Under Docker keepDB_HOST=mysqlandAPP_ROOT=(empty) in.env. -
server startdoes nothing through.bin/caligraferwhile a local Apache runs (G25): it serves the project itself. Stop it, or runphp caligrafer.php server start.
- Caligrafer: every command
- Quickstart · Quickstart with Claude
- Installation and configuration
- API reference: framework and tooling
Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.
Why Caligrafy: the benefits, the measurements, and what it is not yet
-
Quickstart with Claude: describe it, approve it, ship it
or the Quickstart: the same three steps by hand, in 5 minutes
- How Caligrafy works: the ideas in 5 minutes
- Your first capability: build a feature, page included
-
Capabilities in depth
-
#[Capability]: every option - Scheduled jobs: capabilities on a timer
- Notifications: web push and email
- Background jobs: capabilities run later
- Migrations: database changes, in order
- The cache
-
Testing your app
- Dependency injection
- Validation rules
-
Web pages
- Views and page components
- Design styles: another look, one setting
- Declarative routes: every request, in one line
-
Route::page·Route::form·Route::auth·Route::webhook·Route::download·Route::redirect·Route::action·Route::snap· capability routes - How to export a list as CSV
- Controllers: moving one to a declared route · how to, step by step
- Forms and helpers
-
Vue apps
-
Mobile and tablet
-
REST API
-
AI agents
-
Snap Cards and the assistant
- Payments: Stripe and crypto
- Face detection and face login
- OpenAI: chat and images · Assistants
- Open models: Llama, Mistral...
- Chatbots with Watson
- Machine learning in the browser
- Metadata and social cards · search and analytics
-
Putting it online: the production image, the database at every start
-
API reference: every class and method
-
Routing ·
Route·AuthRoutes· pages ·Controller· capabilities -
Data ·
Model·Query· sign-in · jobs ·Notify· payments · AI -
Interfaces · Snap ·
Snap\Cards·Snap\Conversation· testing · tooling · helper functions
-
Routing ·
-
Caligrafer: every command
- Project · build · data · agents · jobs and tests · maintenance · deploy
- Installation, configuration and Caligrafer
- Routing · Request · Controllers · Views
- Vue: flow of information · routes · validations
- Security and upgrading
- Release notes: 2.26 · 2.25 · 2.24 · 2.23 · 2.22 · 2.21 · 2.20 · 2.19 · 2.18 · 2.17 · 2.16 · 2.15 · 2.14 · 2.13 · 2.12 · 2.11 · 2.10 · 2.9 · 2.8 · 2.7 · 2.6 · 2.5 · 2.4 · 2.3 · 2.1 · October 2026 · changelog
- Testing Caligrafy (contributors)