Repository navigation
Caligrafer Build Commands
The build commands of Caligrafer make features:
service writes a capability, capabilities lists them, call runs one from the terminal, client writes their
JavaScript client, and app, create, facedetect, ml and bot create client apps in public/.
/caligrafy-quill:new-capability create_book books:write
/caligrafy-quill:new-app facedetect faces
new-capability runs service, fills the class, serves it, runs client and checks it with call;
new-app runs the app command and writes its routes.
Check before you say OK: php caligrafer.php capabilities lists the new capability with the scope you asked for,
and php caligrafer.php call <name> ... answers {"data": ...}.
docker compose exec dev-box php caligrafer.php service Bookshelf/CreateBook --scope books:write
docker compose exec dev-box php caligrafer.php capabilities
docker compose exec dev-box php caligrafer.php call create_book title=Dawn published_year=1987 author_id=2
docker compose exec dev-box php caligrafer.php client(without Docker, drop docker compose exec dev-box). Your first capability
walks through the whole feature.
Usage: php caligrafer.php service <Name> [--scope <resource:action>] [--read-only]
Name in PascalCase, optionally in folders: Books/CreateBook
php caligrafer.php service Bookshelf/CreateBook --scope books:write
php caligrafer.php service Bookshelf/ListBooks --scope books:read --read-only Created application/services/Bookshelf/CreateBook.php: capability 'create_book' (scope books:write)
Fill in $rules and handle(), then serve it: a page (Route::page data), a form (Route::form), REST (Route::capability or Route::capabilities), MCP (Route::mcp)
-
The name must be PascalCase, optionally in folders (
Books/CreateBook). The capability is the snake_case of the class:CreateBookgivescreate_book. -
The file is
application/services/<Name>.php, written fromframework/settings/service.php.template: a class that extendsCaligrafy\Service, a#[Capability(...)]attribute withname, a placeholderdescription,scopeandreadOnly, empty$rules,$filtersand$descriptions, and ahandle(array $input, Context $context)that returnsarray(). -
--scopefillsscope:. Without it the capability needs no scope: anyone signed in, and any token, may call it. -
--read-onlysetsreadOnly: true(a page may read it; agents see it as safe). - It refuses an existing file (
<file> already exists) and a project withoutapplication/(application/ not found: run php caligrafer.php initialize first), both with exit code1. - The other options of the attribute (
public,level,destructive,async,webOnly) are added by hand.
What each part of the class means is in the API reference:
Caligrafy\Service and
Caligrafy\Capability.
capabilities [--json | --markdown]: the capabilities of application/services/ (what REST, MCP and the JS client can call)
php caligrafer.php capabilities # one line each
php caligrafer.php capabilities --markdown # a table for your documentation
php caligrafer.php capabilities --json # with the input schemas create_book books:write writes Adds a book to the Bookshelf catalog and returns it with its id and its author.
get_book public read Returns one book of the catalog with its author (id, name, bio), by the id of the book.
| Column | What it says |
|---|---|
| 1 | the capability's name |
| 2 | who may call it: public, its scope, or signed in when it has no scope |
| 3 |
read (readOnly), destroys (destructive) or writes
|
| 4 | its description |
-
--markdownprints| Capability | What it does | Scope | Inputs |, with(read-only)or(destructive)after the name and(required)after each required input. -
--jsonprints, for each one,name,description,scope,level,readOnly,destructive,publicandinput, its JSON Schema (Capabilities::describe()). - The framework's own capabilities (users, notifications,
queue_work...) are listed too. Web-only capabilities are not: onlyRoute::actionreaches them. - With none:
No capabilities yet: php caligrafer.php service <Name> creates one in application/services/.
Usage: php caligrafer.php call <capability> ['{"key": "value"}' | key=value ...] [--token <token>] [--guest]
Lists the capabilities: php caligrafer.php capabilities
php caligrafer.php call list_books
php caligrafer.php call get_book id=3
php caligrafer.php call create_book '{"title": "Dawn", "published_year": 1987, "author_id": 2}'
php caligrafer.php call create_book title=Dawn published_year=1987 author_id=2 --guest # a visitor who is not signed in
php caligrafer.php call create_book title=Dawn published_year=1987 author_id=2 --token cq_... # as a token-
Inputs: one JSON object,
key=valuepairs, or both (merged in order). Anything else stops withcaligrafer call: '<arg>' is neither JSON nor key=value. Akey=valuevalue is a string; the capability's rules check it as they check a form's values. -
Who calls: without
--tokenor--guest, the command line, with full access, like any script you run (cliin the audit log).--guestis a visitor: only public capabilities.--token <token>, or theCALIGRAFY_TOKENenvironment variable, calls as that token, with its scopes; it needs the database, and a token that is unknown, revoked or expired stops withcaligrafer call: The token is unknown, revoked or expired. -
The answer is the JSON of REST, printed with indentation:
{"data": ...}and exit code0, or{"error": {"code": "invalid", "message": "...", "fields": {...}}}and exit code1. - It never loads
application/config/config.php(G141): a validator added there withGUMP::add_validator()does not exist on the command line.
client [<file>] [--prefix /capabilities]: writes the JS client of the capabilities (default public/js/capabilities.js)
php caligrafer.php client # public/js/capabilities.js
php caligrafer.php client public/myspa/src/capabilities.js # a single page application
php caligrafer.php client --prefix /api/capabilities # Route::capabilities('/api/capabilities') public/js/capabilities.js written: 21 capabilities, calls /capabilities (Route::capabilities('/capabilities') in web.php)
import { createBook, CapabilityError } from './capabilities.js'
- One ES module with no dependency: one
export constper capability (create_bookbecomescreateBook), each with a doc comment made of the capability's description, its access and its inputs; pluscall(name, input),capabilities(),configure({ baseUrl, token, prefix, credentials })andCapabilityError(status,code,fields). - Web-only capabilities and Snap's own (
snap_*) are left out. -
--prefixmust match theRoute::capabilities(...)ofweb.php. - Run it again after every change to a capability.
-
Could not write <file>and exit1when the folder cannot be written.
Learn more in the JS client
and Caligrafy\Client.
create <project_name>: scaffolds a Vue project
app <project_name>: scaffolds a regular Client HTML/JS project
bot <bot_name>: creates a bot application
facedetect <app_name>: creates a face detection application
ml <app_name>: creates an ml powered application
| Command | Copies | Into | What it is |
|---|---|---|---|
app catalog |
framework/plugins/app |
public/catalog |
Vue 3 as a library |
create myspa |
framework/librairies/app |
public/myspa |
a Vite Vue single page application; npm install when npm is there |
facedetect faces |
framework/plugins/facedetect |
public/faces |
face detection and recognition |
ml lab |
framework/plugins/ml |
public/lab |
machine learning in the browser (ml5, p5) |
bot helper |
framework/plugins/bot |
public/helper |
a Watson chatbot |
Project created in the public folder.
Type cd public/catalog to access it anytime
-
The page route of the app is not written by the command: add it to
web.php(the Vue pages show it), or let/caligrafy-quill:new-appdo it. -
Names that are refused:
app,bot,__bots__,css,facedetect,fonts,images,js,ml,resources,uploads(folders ofpublic/the framework uses). A folder that exists already printspublic/<name> already exists: nothing was created.and exits with1. -
createand Node.js. It runsnpm installonly wherenpmexists. The Dockerdev-boxhas no Node.js, so there it printsVueJS project created, but its packages are NOT installed: npm is not available here (the Docker dev-box has no Node.js).(G62): runnpm install, thennpm run dev, inpublic/<name>on your computer, with Node.js 20.19+ or 22.12+. -
A Vite app online is served from its committed
dist/: runnpm run buildand commit it, because the production image has nonpm.
Learn more: Vue as a library, the single page application, face detection, machine learning, chatbots.
-
A capability with no
--scope: any token can call it. Give every capability that changes data a scope. -
The client is out of date: a capability added or changed after
clientran is missing fromcapabilities.js, or called with old inputs. Runclientagain. -
A custom validator works on pages but not with
call(G141):call, the scheduler and the queue never loadconfig.php. Register it where the command line loads it too, or use a built-in rule. -
call ... | jqhides a refusal (G89): the pipe reportsjq's exit code. Useset -o pipefail, or read theerrorkey.
- Caligrafer: every command
- Your first capability
- Capabilities in depth
- API reference: services and capabilities
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)