This guide gets the Forge Kernel up and running on your machine. It's the bootstrap — what you actually build on top of it, you choose from the catalog.
Note: Forge doesn't require Composer. The Kernel is dependency-free. Database, routing, and views are capabilities you install when your app needs them.
# Quick install with one command
bash <(curl -Ls https://raw.githubusercontent.com/forge-kernel/installer/main/installer.sh)Running this launches a little wizard that walks you through scaffolding a new project. It fetches the registry of available blueprints and lets you pick one — a blueprint is a starter you build on top of, each bundling a different set of capabilities from the start.
What the wizard asks:
pick a
blueprint (for
example blank
for a bare project with just the
package manager, or a web starter
like
minimal-http
that already wires in routing and
views), answer any optional
configuration options the blueprint
offers, then give a project name or
path. Run the installer with
--list
to see what's available without
installing.
On confirm, the scaffolder downloads the chosen
template, installs the Kernel, drops in the package
manager, and installs the blueprint's bundled
capabilities (running
package:install-project) — giving you a working Forge app you can run
immediately. Prefer non-interactive setup? See the
manual installation
below.
If you prefer to skip the interactive prompts, pass flags to the installer (they're forwarded to the scaffolder) instead:
# Pick a blueprint and auto-confirm (no prompts)
bash <(curl -Ls https://raw.githubusercontent.com/forge-kernel/installer/main/installer.sh) my-app --blueprint=minimal-http --yes
# Scaffold into the current directory instead
bash <(curl -Ls https://raw.githubusercontent.com/forge-kernel/installer/main/installer.sh) . --blueprint=blank
# List available blueprints without installing
bash <(curl -Ls https://raw.githubusercontent.com/forge-kernel/installer/main/installer.sh) --list
Whatever way you scaffold, you end up with a
working app — Kernel installed, package manager in
place, and the blueprint's bundled capabilities
already set up. From there, how you run it depends
on what the blueprint gave you:
php forge.php serve
runs a web app locally, but that command comes
from the routing capability (ForgeRouter).
If your blueprint is web-oriented (like
minimal-http), serve is ready to go; a bare
blank
blueprint has no HTTP yet, so install a router via
the package manager
before
you expect a
serve
command to exist.
Forge uses environment variables for
configuration. Edit your
.env
file:
# Application Settings
APP_NAME="My Forge App"
APP_ENV=development
APP_DEBUG=true
APP_KEY=your-generated-key
FORGE_DEVELOPER_MODE=false
# Cache Configuration
CACHE_DRIVER=file
# Session Configuration
SESSION_DRIVER=file
SESSION_LIFETIME=1440Start the development server to test your installation:
php forge.php serve
Visit
http://localhost:8000
to see your application running. Note that
serve
is an HTTP concern — it exists once the
routing capability (ForgeRouter) is present, which
a web blueprint includes from the start. Database
connection settings (like
DB_*
keys) only come into play once you install a
database capability — see
ForgeDatabaseSQL.
The Kernel gives you the foundation. Everything an HTTP app actually needs — routing, views, and a database — comes from capabilities you install. Pick the ones your app needs:
Prerequisite: these behaviors are capabilities, not kernel built-ins. Install them through the ForgePackageManager before you write routing, views, or database code. The catalog lists everything available.
HTTP routing, controllers, middleware, and requests — via ForgeRouter.
Plain PHP views, layouts, and components — via ForgeView.
SQL databases and an ORM — via ForgeDatabaseSQL and ForgeSqlOrm.
Auth, storage, events, and more — browse the full catalog.
Forge includes a retro-styled interactive command
browser that makes it easy to discover and
execute commands. Run
php forge.php
without any arguments to access it.
Features: splash
screen (skippable with
--no-splash), multi-column listings that adapt
to your terminal width, category-based
browsing, and the ability to execute
commands or view help directly from
the interface. Use arrow keys to
navigate and Esc to exit.
# Launch interactive command browser
php forge.php
# Skip splash screen
php forge.php --no-splash
# Show traditional command list
php forge.php --list
# Generate a controller (wizard, or skip with options)
php forge.php generate:controller
php forge.php generate:controller --type=app --name=UserCommands that belong to a capability (like database migrations or package management) only appear once that capability is installed — another reason to install what you need.
Developer mode unlocks advanced CLI commands for working with registries and publishing kernel/capability versions. You only need it if you're building your own kernel fork or publishing capabilities — not for regular app development.
FORGE_DEVELOPER_MODE=true
When enabled, commands like
dev:kernel:publish
and
dev:module:version
become available. See
Forging Your Own
for the full story on building and publishing
your own kernel and capabilities.