Connecting your apps

Updated

Crate is a provider: your other applications install packages from it. What authenticates is Composer, during composer install or composer update, so any PHP project with a composer.json can use Crate. The artisan-build/crate-client package is a convenience for Laravel applications that writes Composer's auth file from two environment values.

Attach an application through Scalpels

For an application your team runs on Laravel Cloud or Laravel Forge, attach it to your Crate from Scalpels. The steps, requirements and refusals are in Attach to an existing app.

For Crate, attaching:

issues a registry credential on your Crate for that application;
writes CRATE_URL (your Crate's address) and CRATE_TOKEN (the credential) into the application's environment;
opens a draft pull request that adds your Crate installation as the named crate Composer repository, adds artisan-build/crate-client at ^0.2 to composer.json, adds CRATE_URL and an empty CRATE_TOKEN to .env.example, and adds /auth.json to .gitignore.

Scalpels never shows you the credential and never merges the pull request.

Finish the pull request

Check out the pull request's branch. The pull request already adds the named crate Composer repository at your Crate installation's URL, so you do not need to run composer config repositories.crate yourself.

Run the composer update command shown in the pull request, commit composer.lock, then review and merge.

crate-client requires PHP 8.3 or newer and Laravel 13.

Give Composer the credential

With CRATE_URL and CRATE_TOKEN in the environment, write Composer's auth:

php artisan crate:auth

This writes or merges an http-basic entry for your Crate's host into auth.json in the current directory, with the username token and CRATE_TOKEN as the password. Other entries in the file are kept. Use --path=/somewhere/auth.json to write elsewhere.

For CI or a build step, print the JSON instead and pass it to Composer through COMPOSER_AUTH:

export COMPOSER_AUTH="$(php artisan crate:auth --print)"

Do not run --print anywhere its output is kept, such as an agent tool call or a logged CI step, because it contains the credential. Never commit auth.json.

If CRATE_URL or CRATE_TOKEN is missing, or CRATE_URL has no valid host, crate:auth reports the error and exits unsuccessfully.

Without the client package

Any Composer project can use Crate with two commands and a credential from Settings on your Crate (see Credentials):

composer config repositories.crate composer https://crate.example.com
composer config --auth http-basic.crate.example.com token "<credential>"

Verify the connection

Pick a package your Crate serves, then from the application's directory:

php artisan crate:auth
composer show vendor/private-package --all

A working connection exits with status 0 and prints the package's name and versions. Then composer require vendor/private-package installs it as usual.

A 401 means Composer reached Crate but the credential was not accepted: it is missing, wrong, revoked, or not a registry credential. Crate does not say which. See Troubleshooting.