README

Declarative application deployments through provider plugins.

Shipper reads shipper.yml, validates the selected project and profile, shows the planned operations, and delegates deployment work to the installed provider package.

Install

Install globally with Composer:

Deployment Features

✅ Declarative YAML configuration (shipper.yml)
✅ Multiple projects and deployment profiles (production, staging, preview)
✅ Pluggable provider system with provider packages (shippercli/provider-ploi, shippercli/provider-forge, shippercli/provider-cpanel, shippercli/provider-easypanel)
✅ Plan/apply workflow for safe deployments
✅ Configuration validation
✅ GitHub Actions workflows for CI/CD
✅ Database configuration and automatic provisioning
✅ Database lifecycle management (create, link, destroy)

composer global require shippercli/cli

Or work from source:

composer install
./shipper list

Prebuilt PHAR binaries are published on the releases page.

Provider packages

Providers are separate Composer packages:

Provider	Package
Ploi	`shippercli/provider-ploi`
Laravel Forge	`shippercli/provider-forge`
cPanel	`shippercli/provider-cpanel`
EasyPanel	`shippercli/provider-easypanel`

Install the package for the target platform:

composer global require shippercli/provider-cpanel

Shipper discovers packages with Composer's runtime plugin metadata. Provider credentials, platform features, and configuration options belong to each provider's documentation rather than the core CLI.

Configure

Create shipper.yml in the application repository:

providers:
  provider_name:
    api_token: "${PROVIDER_API_TOKEN}"

projects:
  backend:
    provider: provider_name
    path: "."
    web_directory: /public
    profiles:
      production:
        branch: main
        domain: "api.example.com"
      staging:
        branch: develop
        domain: "api.example-test.com"

provider_name is the slug registered by the installed package. Profiles can override provider-supported runtime, database, domain, environment, and lifecycle options.

Environment placeholders use ${NAME} syntax and are resolved at runtime. Keep credentials in the shell, CI secrets, or another secret manager.

Commands

# Validate all configured projects and profiles.
shipper validate

# Preview provider operations without changing remote state.
shipper plan backend --profile=production

# Apply a deployment. --force skips the confirmation prompt.
shipper apply backend --profile=production --force

# Inspect provider-defined deployment and resource state.
shipper status backend --profile=production

# Read recent provider or application log lines.
shipper logs backend --profile=production --lines=100

# Restore the latest or a named provider-managed release.
shipper rollback backend --profile=production
shipper rollback backend --profile=production --release=release-id

# Remove only resources the provider identifies as Shipper-managed.
shipper destroy backend --profile=preview --force

status, logs, and rollback are optional provider capabilities. Shipper returns a clear error when the selected provider does not implement one.

Provider contracts

Every provider implements validation, planning, apply, destroy, name, and error-reporting methods from shippercli/contracts.

Optional contracts add:

deployment status
recent logs
release rollback
server provisioning and cleanup

The CLI adapts installed contract providers to its internal flows. Provider implementations do not belong in the core repository.

GitHub Actions

A minimal deployment workflow validates before applying:

name: Deploy

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          extensions: yaml, zip

      - run: composer install --no-interaction --prefer-dist
      - run: ./shipper validate
      - run: ./shipper apply backend --profile=production --force
        env:
          PROVIDER_API_TOKEN: ${{ secrets.PROVIDER_API_TOKEN }}

See GitHub Actions for production, staging, preview, cleanup, and reusable-action patterns.

Documentation

Documentation index
Configuration
Provider operations
Server lifecycle
Sites
Databases
PR previews
GitHub Actions
Build and releases
Configuration Guide - Complete shipper.yml configuration reference
Server Lifecycle - Existing servers, managed preview servers, and cleanup rules
PR Previews - Set up preview environments for pull requests
Sites Management - Managing site lifecycle and deployment
Database Management - Database configuration and operations
GitHub Actions Setup - Automated deployments with GitHub Actions
GitHub Action Usage - Using Shipper as a reusable GitHub Action
Build System - Understanding the build and release process
Strict Standards - Code quality and type safety standards
Roadmap - Planned features and Ploi.io configurations not yet supported

Development

composer format
composer format:check
composer analyse
XDEBUG_MODE=coverage composer test
composer build

The codebase targets PHP 8.3+, Laravel Pint, PHPStan level 9, and Pest.

Release

Tags build and publish the PHAR through GitHub Actions:

git tag v1.0.0
git push origin v1.0.0

License

MIT

shippercli / cli

Maintainers

Package info

Statistics

Security