Forge
@goodcraft/forgev2026.07.21.2
01README
Laravel Forge (API v2, org-scoped) — list servers, audit and idempotently provision sites (git-backed or repo-less, e.g. a reverse proxy to a Node app), set a site's .env from a vault reference, read and replace a site's nginx config, run root-level Bash on a server via Forge recipes, install LetsEncrypt SSL, and manage deployments (set deploy script, deploy with polling, read the deploy log).
02Release Notes
Add describeSite, getNginx, setNginx, runRecipe
03Models
@goodcraft/forgev2026.07.21.2forge.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiToken | string | |
| organization | string | |
| baseUrl | string |
fn sync()
List all servers in the Forge organization (read-only, v2 API)
fn auditSite(sites: array)
Detect which expected sites exist across servers (read-only; ready=true means all present)
| Argument | Type | Description |
|---|---|---|
| sites | array |
fn provisionSite(repository?: string, dryRun: boolean, composer: boolean, sites: array)
Idempotently provision sites: v2 creates the site with git attached in one call (type laravel, custom domain), then sets the deploy script. composer=false by default (monorepos without a root composer.json). Per-site zeroDowntime=true opts into Forge's atomic release layout (current/ symlink + shared storage and .env); it only applies to sites this call creates, since Forge fixes the layout at creation time. dryRun=true (default) plans without writing. First deploy is out of scope (needs .env +
| Argument | Type | Description |
|---|---|---|
| repository? | string | |
| dryRun | boolean | |
| composer | boolean | |
| sites | array |
fn setEnv(server: number, domain: string, env: string)
Write a site's .env from supplied content (pass `env` as a vault expression so secrets never appear in args/logs). Stores only key names + byte count, never values.
| Argument | Type | Description |
|---|---|---|
| server | number | |
| domain | string | |
| env | string |
fn installSsl(server: number, domain: string, domains: array, dryRun: boolean)
Obtain and install a LetsEncrypt SSL certificate for a site's bare (non-www) domain via the v2 domain-record flow. Idempotent (skips when the domain record already has an active certificate). DNS must already point at the server. dryRun=true (default) plans without requesting a certificate.
| Argument | Type | Description |
|---|---|---|
| server | number | |
| domain | string | |
| domains | array | |
| dryRun | boolean |
fn deploy(server: number, domain: string, wait: boolean, dryRun: boolean)
Trigger a Forge deployment for a site (runs its deploy script) and optionally poll until it finishes. dryRun=true (default) plans without deploying.
| Argument | Type | Description |
|---|---|---|
| server | number | |
| domain | string | |
| wait | boolean | |
| dryRun | boolean |
fn deployLog(server: number, domain: string)
Fetch the latest deployment log for a site (read-only) — useful for diagnosing a failed deploy.
| Argument | Type | Description |
|---|---|---|
| server | number | |
| domain | string |
fn setDeployScript(server: number, domain: string, script: string, dryRun: boolean)
Set a site's deployment script (PUT). dryRun=true (default) plans without writing.
| Argument | Type | Description |
|---|---|---|
| server | number | |
| domain | string | |
| script | string | |
| dryRun | boolean |
fn describeSite(server: number, domain: string)
Read back a site's raw v2 record and its domain records (read-only). Use it to inspect the exact values Forge assigned — type, web_directory, www_redirect_type — e.g. before mirroring an existing site onto a new server.
| Argument | Type | Description |
|---|---|---|
| server | number | |
| domain | string |
fn getNginx(server: number, domain: string)
Read a site's nginx configuration file (read-only). Pair with setNginx to add a reverse-proxy block for an app Forge does not manage natively (Ghost, or any Node service on a local port).
| Argument | Type | Description |
|---|---|---|
| server | number | |
| domain | string |
fn setNginx(server: number, domain: string, content: string, dryRun: boolean)
Replace a site's nginx configuration file. Forge validates and reloads nginx; a config that fails `nginx -t` is rejected. dryRun=true (default) plans without writing.
| Argument | Type | Description |
|---|---|---|
| server | number | |
| domain | string | |
| content | string | |
| dryRun | boolean |
fn runRecipe(name: string, script: string, servers: array, user: string, dryRun: boolean, wait: boolean, timeoutSeconds: number)
Run a Bash script on one or more servers as a given user (default root) via Forge's recipe mechanism, then poll for the run output. This is the supported way to do root-level work on a server whose `forge` user requires a sudo password. The recipe is upserted by name, so re-running replaces the script rather than accumulating copies. dryRun=true (default) plans without creating or running anything.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| script | string | |
| servers | array | |
| user | string | |
| dryRun | boolean | |
| wait | boolean | |
| timeoutSeconds | number |
Resources
servers(infinite)— Snapshot of the servers in the Forge organization
siteReadiness(infinite)— Readiness audit of a set of expected sites across servers
provisionResult(infinite)— Outcome of the last provisionSite run
envResult(infinite)— Non-sensitive summary of the last setEnv call (no secrets)
sslResult(infinite)— Outcome of the last installSsl call (LetsEncrypt certificate)
deployResult(infinite)— Outcome of the last deploy call
deployLog(infinite)— Latest deployment log for a site (read-only)
deployScriptResult(infinite)— Outcome of the last setDeployScript call
siteDetail(infinite)— Raw v2 site record and its domain records (read-only)
nginxConfig(infinite)— A site's nginx configuration file (read-only)
nginxResult(infinite)— Outcome of the last setNginx call
recipeRun(infinite)— Outcome of the last runRecipe call
04Previous Versions
2026.07.21.1
Add optional per-site zeroDowntime to provisionSite. Forge fixes the release layout at site-creation time, so sites created without it get in-place deploys; passing zeroDowntime: true opts into the atomic layout (current/ symlink, shared storage and .env) that GoodCraft's deployed apps use. Only applies to sites the call creates — it cannot convert an existing site. The provisionResult actions echo the flag for sites being created. README documents the absolute-web_directory consequence for auditSite expectations and the bootstrap-storage dependency.
2026.07.02.4
2026.07.02.3
2026.07.02.2
2026.07.02.1
2026.06.14.3
Modified 1 models
2026.06.14.2
Modified 1 models
2026.06.14.1
05Stats
A
100 / 100
Downloads
2
Archive size
26.4 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
06Platforms
07Labels