laravel-cloud-blueprint/cli

Declarative Infrastructure as Code for Laravel Cloud.

Maintainers

Package info

github.com/eroltukenmez/laravel-cloud-blueprint

pkg:composer/laravel-cloud-blueprint/cli

Transparency log

Statistics

Installs: 10

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v0.1.0-alpha.3 2026-08-25 11:46 UTC

Requires

Requires (Dev)

MIT e232385de77154d5c9054ca1d90e47a5c8b19965

Published on Packagist.org on 2026-08-25 11:49 UTC

This package is not auto-updated.

Last update: 2026-08-26 06:47:48 UTC

README

Laravel Cloud Blueprint is a framework-agnostic CLI for describing and reconciling Laravel Cloud infrastructure using version-controlled YAML blueprints.

Warning

Version 0.1.0-alpha.3 is early alpha software with a deliberately limited mutation model. This is an unofficial community project and is not affiliated with or maintained by Laravel.

Why

Laravel Cloud exposes an API. Laravel Cloud Blueprint provides an experimental declarative YAML workflow around the subset of that API currently supported by this project: applications, environments, and environment variables.

Status

Current version: 0.1.0-alpha.3.

This release can discover and compare applications, environments, and environment variables. It can create missing applications, environments, and variables; update an environment's branch; and update an existing variable's value. Application repository and region changes remain unsupported.

Requirements

  • PHP 8.3 or newer
  • Composer
  • A Laravel Cloud API token for Cloud reads and mutations
  • A GitHub, GitLab, or Bitbucket repository connected to Laravel Cloud

Installation

Install the current alpha release globally through Composer:

composer global require laravel-cloud-blueprint/cli:^0.1@alpha
lcb --version

Expected output:

Laravel Cloud Blueprint 0.1.0-alpha.3

Composer's global bin directory must be available in PATH for the lcb command to be found.

Authentication

Set your Laravel Cloud API token in the process environment:

export LCB_TOKEN="your-token"

Never commit API tokens or place them in blueprint files.

Quick Start: New Infrastructure

lcb init
lcb validate
lcb plan
lcb apply

apply displays a fresh plan and asks for confirmation, defaulting to no. Use --auto-approve for automation. --non-interactive explicitly disables prompting and refuses changes unless combined with --auto-approve; JSON apply output likewise requires --auto-approve when changes are present.

Quick Start: Existing Laravel Cloud Application

lcb init --from-cloud

If Laravel Cloud does not return source-provider metadata, provide it explicitly:

lcb init --from-cloud --provider=github

This performs read-only Cloud discovery and exports supported application and environment structure only. It does not create .lcb/state.json, import or adopt state ownership, export environment-variable values or secrets, or persist remote IDs. Existing resources remain unmanaged. Later supported reconciliation against a matched remote resource does not implicitly adopt it into state. The command refuses to overwrite an existing file unless --force is supplied; review generated output before applying it.

Blueprint Example

version: 1

organization: my-organization

application:
  name: my-api
  region: eu-central-1
  source:
    provider: github
    repository: acme/my-api

environments:
  production:
    branch: main
    variables:
      APP_ENV:
        value: production

      APP_KEY:
        from_env: APP_KEY
        sensitive: true

value supplies a literal string. from_env resolves a value from the local process environment when needed for reconciliation, including the fresh plan performed by apply. sensitive: true marks intent but does not weaken or strengthen output redaction; it does not create or use a Laravel Cloud Secrets Manager secret.

See examples/cloud.blueprint.yaml for a complete safe example.

Commands

init

Creates a starter blueprint. --file=<path> selects the output path and --force permits overwrite.

--from-cloud generates a blueprint through read-only Cloud requests. With multiple applications, select interactively or use an exact --application=<name-or-slug>. --non-interactive refuses ambiguous selection. --provider=github|gitlab|bitbucket supplies provider metadata when the API omits it.

validate

Validates the current v1 schema locally. Use --file=<path> for a non-default blueprint.

cloud:inspect

Reads the authenticated organization, applications, and environments without mutation. Supports --json.

plan

Creates a read-only comparison against Laravel Cloud. Supports --file=<path> and --json.

apply

Creates and updates supported resources after producing a fresh plan. Supports --file=<path>, --auto-approve, --non-interactive, and --json.

Run lcb <command> --help for exact usage.

Plan Semantics

  • CREATE: a supported desired resource is missing remotely.
  • UPDATE: a supported mutable field differs remotely (environment branch or variable value).
  • NO_CHANGE: the remote resource matches the blueprint.
  • UNSUPPORTED: satisfying the difference would require behavior unavailable in this release.

Text plans use + for create, ~ for update, = for no change, and ! for unsupported. The summary reports counts to create, update, leave unchanged, and treat as unsupported; JSON output exposes the same four counts.

Planning is read-only and deterministic. Extra remote resources are not deleted. Application repository and region differences are reported as unsupported, so they cannot be accidentally applied.

Apply Semantics

Apply always creates a fresh plan, refuses the entire plan before Cloud mutation when any unsupported action is present, and requests approval unless auto-approved. Interactive approval defaults to no. After approval and preflight checks it acquires the state lock for managed mutation and state work. Potentially duplicate-creating POST requests are never automatically retried.

Supported work is processed in dependency order: application, environments, then environment-variable groups. Environment branch updates use Laravel Cloud's environment PATCH endpoint and accept a confirmed success response without requiring an attributes.branch string. Variables are sent per environment with Laravel Cloud's method=set mode for both create and update.

Successful application and environment creations are checkpointed as work progresses. Environment branch updates retain their remote identity and do not cause a state save or serial increment solely because of the update. Variables remain outside state, so variable updates likewise do not save or increment state. A pure supported UPDATE apply leaves .lcb/state.json unchanged; a mixed CREATE + UPDATE apply can change it when a successful CREATE identity is checkpointed. A later failure is reported as partial, with completed checkpoints retained, and confirmed remote mutations are not rolled back.

State

Local state is stored in .lcb/state.json. It contains remote IDs for LCB-managed application and environment resources. Variables are not state resources, and their values are never stored.

State uses local locking and atomic replacement and should not be edited manually. init --from-cloud neither creates state nor adopts remote resources into existing state.

Security

  • API tokens are never written to blueprints or state.
  • Environment-variable values are not printed in plans or apply results and are not persisted in state.
  • Use from_env for secret material.
  • Blueprint value fields are literal and version-controlled; do not place secrets in them.
  • sensitive: true is LCB redaction metadata, not Laravel Cloud Secrets Manager integration.

See SECURITY.md for vulnerability reporting guidance.

Known Limitations

  • This is early alpha software with a limited mutation model.
  • Environment branch and variable value updates are supported; other updates and renames are not. A variable-key change is not an in-place rename and cannot remove the old remote key.
  • Application repository changes are explicitly unsupported because changing a repository can affect existing environment branch relationships in Laravel Cloud, requiring a broader lifecycle/rebinding workflow than this release implements. No repository mutation request is sent.
  • Application region changes are unsupported.
  • DELETE, destroy, import/state adoption, drift repair, and remote state are not supported.
  • Databases, caches, storage, domains, and Secrets Manager are not supported.
  • init --from-cloud does not export environment variables or secrets.
  • Source-provider metadata may be absent from API responses and require --provider.
  • Environment-variable mutation uses Laravel Cloud's method=set request mode for both creates and updates.
  • A variable missing during plan could be created externally before apply; because Cloud provides set rather than conditional create, apply could then update that key.
  • Variable values are omitted or redacted from text and JSON plan/apply output, state, and safe exceptions regardless of whether sensitive: true is set; Cloud validation and transport errors are sanitized before display.
  • Laravel Cloud API behavior may evolve during the alpha lifecycle.

Roadmap

  • Database and cache resources
  • Richer planning and update semantics
  • Import and state adoption
  • Destroy and drift detection
  • Distribution improvements

No release dates are promised for roadmap items.

Development

git clone https://github.com/eroltukenmez/laravel-cloud-blueprint.git
cd laravel-cloud-blueprint
composer install
composer test
composer analyse

From a repository checkout, invoke the CLI as php bin/lcb. PHPStan runs at maximum level. Tests use fakes and do not require a live Laravel Cloud account.

Contributing

See CONTRIBUTING.md.

License

Laravel Cloud Blueprint is released under the MIT License.