Cli Laravel Package

Getting Started

This release (v1.0.3) is about distribution, not new behaviour: the shipper CLI is now published as a standalone binary alongside its SHA-256 checksum and GitHub build provenance, and the Composer CLI binary is exposed as part of the release workflow (PR #103). For a Laravel developer, the practical takeaway is that you no longer need a Composer install step to get the tool onto a machine or into CI.

Minimal path to first value:

1. Grab the shipper binary from the v1.0.3 release assets (pick the artifact matching your OS/arch).
2. Verify it before you run it:

   sha256sum -c shipper.sha256   # or: shasum -a 256 -c
   

3. Make it executable and smoke-test:

   chmod +x shipper
   ./shipper --version
   

4. Read the README next — this release explicitly defers to it for full documentation, and there is no Laravel-specific surface area documented here (no service provider, facade, or config file).

First use case: drop the verified binary into a CI job or a deploy container and run ./shipper --version as a preflight assertion, so you catch a bad artifact before it touches a deploy step.

Implementation Patterns

Pin the version and the checksum, not just the tag. Store both the release version (v1.0.3) and the expected SHA-256 in your pipeline config or a .shipper-version file at the repo root. Download by explicit URL, never "latest".

Verify provenance in CI. Attach the attestation check to the same job that downloads the binary:

gh attestation verify shipper --repo shippercli/cli

This is the real value of the release — you can now prove the artifact came from the project's build rather than a re-upload.

Cache between jobs, not across versions. Cache the binary keyed on version + checksum so a bumped release invalidates the cache automatically. A stale cache that survives a version bump is the most common way a pin silently stops working.

Wrap it once. Create a thin bin/shipper (or a Make/Envoy task) that resolves the binary, checks the version against your pin, and execs it. Everything else in the repo — Composer scripts, deploy hooks, CI steps — calls the wrapper, so the download/verify logic exists in one place.

Invoke it as an external process from Laravel. Treat the CLI the way you'd treat git or rsync: Process::run() / proc_open in an artisan command, or a hook in Envoy/Deployer. Do not expect it to share Laravel's container, config, or .env — pass configuration via flags and environment variables explicitly.

Keep parity between local and CI. If your team runs the binary locally on macOS and in Linux containers in CI, install the same pinned version on both. Divergent versions produce "works on my machine" failures that look like tool bugs.

Gotchas and Tips

• Executable bit is lost through artifact handling. Zips, some CI artifact uploads, and git-less transfers drop +x. Always chmod +x after extraction rather than assuming it survived.
• Platform/arch mismatches. A binary downloaded for the wrong architecture typically fails with a confusing "cannot execute binary file" rather than a clear error. Assert ./shipper --version right after download so the failure surfaces early.
• macOS Gatekeeper/quarantine. Downloaded binaries can be blocked on first run. xattr -d com.apple.quarantine ./shipper unblocks it locally; don't bake that into CI where it's irrelevant.
• libc differences in containers. If you run on Alpine, confirm the published artifact works there before assuming it does — glibc-linked binaries fail on musl with a misleading error.
• Checksum file naming and paths. sha256sum -c resolves the filename as written inside the checksum file, relative to your CWD. Rename the binary and the check silently fails or errors; either match the name or rewrite the line.
• gh attestation verify needs auth and network. It's not free in an air-gapped runner. Decide explicitly whether provenance verification is a hard gate (recommended for release/deploy jobs) or a soft check.
• Version drift versus a Composer-installed copy. If any part of your stack also pulls the CLI via Composer, you now have two possible sources of truth. Pick one — the standalone binary for CI/deploy is the cleaner story — and make the other explicitly not used.
• Don't curl … | sh in production pipelines. Download, checksum-verify, then execute. The release gives you the checksum precisely so you can avoid that shortcut.
• Watch for behaviour changes hiding in "distribution-only" releases. v1.0.3 is described as exposing the binary, but the changelog is thin on detail. Diff --version/--help output between v1.0.2 and v1.0.3 in a scratch job before rolling it into deploy automation.
• Debugging tip: when the binary misbehaves in CI, first print ./shipper --version and the output of your checksum verification in the failing job's log. Most incidents here are artifact/transport problems, not tool logic.