The official installer

This document outlines the recommended and easiest way to install Castor on your system using the official installer.

Using the installer

The installer is the recommended and easiest way to install Castor on your system. It works on Linux and macOS.

curl "https://castor.jolicode.com/install" | bash

Note

This method will install a phar and thus, it requires PHP >= 8.2 installed on your system.

See the --static option to install a static binary that does not require PHP installed.

Options

--static

If you don't have PHP available on your system, Castor can be installed with a static binary that embeds PHP, so it can be run anywhere.

Use the --static option to install Castor this way:

curl "https://castor.jolicode.com/install" | bash -s -- --static

--install-dir

By default, the installer will install Castor in the current user's $HOME/.local/bin directory.

You can change that by using the --install-dir option:

curl "https://castor.jolicode.com/install" | bash -s -- --install-dir /usr/local/bin

--version

By default, the installer will install the latest version of Castor.

You can install a specific version of Castor by using the --version option:

curl "https://castor.jolicode.com/install" | bash -s -- --version=v1.0.0

Updating Castor

If you installed Castor using the installer (phar or static binary), you can update it to the latest version using the self-update command:

castor self-update

Self-update options

• --force or -f: Force update even if already up to date
• --no-backup: Skip creating a backup of the current binary
• --rollback or -r: Rollback to the previous version

Each release ships a SHA256SUMS file listing the checksum of every binary: the installer and self-update refuse a downloaded binary whose checksum does not match it.

When the GitHub CLI (2.49 or later) is installed and authenticated, the installer and self-update also verify the provenance of the downloaded binary: they check, with gh attestation verify, that the binary was built by Castor's own GitHub Actions workflow. The SHA256SUMS file is attested too, so its provenance can be verified the same way:

gh attestation verify SHA256SUMS --repo jolicode/castor

Note

The self-update command is not available for source installations or Composer project dependencies. For global Composer installs (composer global require), self-update runs composer global update under the hood. For project dependencies, use composer update jolicode/castor instead.

Snapshot builds

Every push on the main branch publishes a snapshot pre-release, so you can try what is coming next before it is released. Install it with:

curl "https://castor.jolicode.com/install" | bash -s -- --version=snapshot

or, from an existing installation:

castor self-update --snapshot

A snapshot reports a version like v1.7.0-14-g4531440: the last release, the number of commits since, and the commit it was built from. To go back to the latest release, run castor self-update without --snapshot.

Note

Right after a push, the installer may still get the previous snapshot for a few minutes: GitHub caches the release downloads by name. self-update is not affected.

Other installation methods

If you cannot use the installer, see the alternative methods documentation.