PHPackages blacklabs/blacklabs - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [CLI & Console](/categories/cli) 4. / 5. blacklabs/blacklabs ActiveProject[CLI & Console](/categories/cli) blacklabs/blacklabs =================== The Black Labs CLI. v2.0.0(1mo ago)023↓100%[4 issues](https://github.com/ChaDonSom/blacklabs/issues)[4 PRs](https://github.com/ChaDonSom/blacklabs/pulls)MITPHPPHP ^8.4CI passing Since May 27Pushed 1mo ago1 watchersCompare [ Source](https://github.com/ChaDonSom/blacklabs)[ Packagist](https://packagist.org/packages/blacklabs/blacklabs)[ Docs](https://blacklabapps.com)[ RSS](/packages/blacklabs-blacklabs/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (2)Dependencies (14)Versions (58)Used By (0) Black labs ========== [](#black-labs) [![Latest Stable Version](https://camo.githubusercontent.com/3e46b414bf47b3ed2bc2dde7d530143fb4ff4bd9473aa81cac15267d58cd7a1b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f626c61636b6c6162732f626c61636b6c6162732e7376673f6c6162656c3d737461626c65)](https://packagist.org/packages/blacklabs/blacklabs) The Black Labs CLI, for our work. Requirements ------------ [](#requirements) 1. The preferred downloadable binaries do not require PHP or Composer on the consuming machine. 2. PHAR installs, Composer-global installs, and local development use PHP `8.4`. 3. You must have `git` installed on your machine ``` sudo apt install git-all ``` 4. You must have `gh` installed for the `create-release-branch` command (it makes a PR for that branch) See [the `gh` install instructions for Linux](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) 5. For the forge commands, you'll need to run `blacklabs app:store-forge-api-token ` first. It will be saved to disk, so you won't need to run it again (until your token expires). Install ------- [](#install) ### Preferred: downloadable binary [](#preferred-downloadable-binary) ``` curl -L https://github.com/ChaDonSom/blacklabs/releases/latest/download/blacklabs-linux-x64 -o blacklabs chmod +x blacklabs sudo mv blacklabs /usr/local/bin/blacklabs blacklabs --version ``` Release assets are intended to be the default install path: - `blacklabs-linux-x64` - `blacklabs-linux-arm64` - `blacklabs-macos-x64` - `blacklabs-macos-arm64` - `blacklabs-windows-x64.exe` ### Fallback: downloadable PHAR [](#fallback-downloadable-phar) ``` curl -L https://github.com/ChaDonSom/blacklabs/releases/latest/download/blacklabs -o blacklabs chmod +x blacklabs sudo mv blacklabs /usr/local/bin/blacklabs blacklabs --version ``` Keep the PHAR executable named `blacklabs` if you want `blacklabs self-update` to keep working against the tagged `builds/blacklabs` file stored in the repository. ### Legacy fallback: Composer global install [](#legacy-fallback-composer-global-install) Make sure Composer is in your system PATH, and has the folders it needs for global installs: [Composer Introduction, #Globally](https://getcomposer.org/doc/00-intro.md#globally) ``` composer global require blacklabs/blacklabs ``` This path now installs the committed PHAR as the package binary while keeping the source application's Laravel dependencies in development-only Composer installs. ### Updating [](#updating) - Downloadable binary: run `blacklabs self-update`. If that fails, replace it with the latest release asset for your platform. - PHAR: run `blacklabs self-update`. If that fails, replace it with the latest `blacklabs` release asset. - Composer global fallback: ``` composer global update blacklabs/blacklabs ``` Usage ----- [](#usage) ### Devops [](#devops) #### Create release branch [](#create-release-branch) ``` blacklabs create-release-branch minor 1001,1002,1003,884,732,1234 ``` This will make a release branch like `release/v0.18.1/1001-1002-1003-884-732-1234` and merge each of those issues into it. You can also specify the version number, like `v0.18.1`, and it will use that instead of incrementing the version number. ``` blacklabs create-release-branch v0.18.1 1001,1002,1003,884,732,1234 ``` > **Note** > > - Use `patch`, or the next 'patch' version number, for hotfix or bugfix releases. > - Use `minor`, or the next 'minor' version number, for feature releases. > - We don't have a true purpose yet for the 'major' number, but the industry standard for Semantic Versioning is: use `major`, or the next 'major' version number, for breaking changes. 1. First, it checks out the `dev` branch and pulls it, to make sure it's up to date. 2. Then, it makes a new branch from `dev` like `release/v0.18.1/1001-1002-1003-884-732-1234` 1. If it finds an existing branch by that name, it will ask you if you want to delete it and remake it. If you respond affirmative, it will do so, if not, it will exit. 3. Then, it goes through each issue number provided and tries to find the branch for it. 1. If it can't find a branch with that issue number in it, it will skip that issue for you to manually merge it in later. 2. If it finds more than one branch with that issue number in it, it will ask you which one to use. 3. Then, having found the branch to merge, it merges it from `origin`. > **Note** > > This means each issue's branch needs to be pushed to origin beforehand. 4. If it runs into a merge conflict, it will pause and ask you to resolve the merge manually. After resolving it, you can tell it to continue. 4. Once the merging is done, it pushes the branch to `origin`. 5. Then, it creates a PR for the release with each issue listed in its description. 6. Then, it adds a tag as well for that version (and pushes it). ### Show site branches [](#show-site-branches) ``` blacklabs show-site-branches ``` This command pings Forge for our servers with the 'console' tag, then displays all their sites along with the git branch they're currently assigned to. This is mainly helpful to get a quick glance while it's a little cumbersome to click through Forge to see it. ### Update site branch and deploy [](#update-site-branch-and-deploy) ``` blacklabs update-site-branch-and-deploy ``` > **Note** > > This command pings Forge (if you haven't given the app a Forge API token yet, do that first: `blacklabs app:store-forge-api-token `). 1. First, it asks you which site to deploy to, out of the list of sites from Forge, filtered by sites that have the 'console' tag. 2. Then, it asks you which branch to deploy. For the options here, it uses `git branch -r` (`-r` for 'remotes', showing only the branches that are pushed to origin). 3. Then, it pings Forge to update that site's branch to the branch you chose. 4. Then, it pings Forge again to initiate deployment for that site. ### Deploy to production [](#deploy-to-production) ``` blacklabs deploy-to-production ``` 1. It will warn you, and you have to type `forge-production` to make it go through. 2. Then, it will ask you which branch to deploy, if you didn't provide the branch as the first argument. 3. Then, it checks out `forge-production`, and merges your chosen branch in. 4. Then, it pushes `forge-production`. 5. Then, it checks out `dev` and merges `forge-production` into it. 6. Then, it pushes `dev`. ### Remerge release branch [](#remerge-release-branch) ``` blacklabs merge-and-increment-tag release/v0.18.1/1002-1003-1120-843-034 843,034 ``` This just helps with merging in the issue branch, then incrementing the tag number. The Forge server handles auto-deploy on its own for this workflow. So, this command would only: 1. Merge the specified issue branches in 2. Increment the tag's deploy number (from the one found in the specified branch) 3. Push the branch and the tags ### Add or Remove Issues from Site [](#add-or-remove-issues-from-site) ``` blacklabs site add-issues blacklabtesting.com 388,3843 ``` 1. It grabs the branch currently deployed to that site. 2. It gets the tag from the `package.json` in that branch (I think; TODO: test that) and increments the `prerelease` number, for example: ``` 0.18.0-2 ^ ``` 3. It comes up with a new list of issues based on the existing list in the branch name, and the ones you listed to add or remove. 4. It creates a new release branch, incrementing the `prerelease` number (see [Create Release Branch](#create-release-branch)) 5. It updates the given site's branch and triggers a deployment on it (see [Update Site Branch and Deploy](#update-site-branch-and-deploy)) ### Checkout to a branch and handle the migrations [](#checkout-to-a-branch-and-handle-the-migrations) ``` blacklabs checkout ``` 1. It checks if any migrations were made in the current branch, and, if so, runs `migrate:rollback`. 2. Then, it checks out to the new branch. 3. Then it checks if any migrations were made in the new branch, and runs `migrate`. > **Warning** > > This command has a bug 🪲 currently, where it can't run migrations in multiple 'steps' (i.e. when you run your migrations using `--step`, or when you make a migration and run it, then make another and run it in a separate process). Contributing ------------ [](#contributing) ### Development install [](#development-install) ``` composer install ``` The Composer package is intentionally thin for global installs: the source application's Laravel, testing, and packaging dependencies live in `require-dev` so end users are encouraged to run the bundled PHAR or downloadable binaries instead of a source-installed dependency graph. ### Deploy process [](#deploy-process) ``` php blacklabs app:deploy ``` This command does: 1. Make sure you're on the repo's default branch 2. Run tests `php blacklabs test` 3. build `php blacklabs app:build` - give it the version 4. Commit it 5. Create a tag for that version 6. Push tags (includes the default branch) 7. The tagged release publishes downloadable artifacts through GitHub Actions: - `blacklabs` (PHAR) - platform-specific packed binaries for Linux, macOS, and Windows ### Features I want to add [](#features-i-want-to-add) 1. A command to switch branches of Console, but reverse any migrations unique to the current branch first. Then, run any migrations that the new branch brings in. There could also be a version of this command for the `composer install` and `npm install`. 2. Laravel Prompts: this would make the CLI interactions prettier and nicer to work with, e.g. selecting 'yes' with the arrow keys rather than typing 'yes', when hitting the merge conflict in creating a release branch. ### Health Score 50 — FairBetter than 95% of packages Maintenance98 Actively maintained with recent releases Popularity7 Limited adoption so far Community9 Small or concentrated contributor base Maturity75 Established project with proven stability Bus Factor1 Top contributor holds 86.8% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~21 days Recently: every ~105 days Total 49 Last Release 44d ago Major Versions v0.6.5 → v1.0.02023-10-25 v1.10.1 → v2.0.02026-03-25 PHP version history (2 changes)v0.0.1PHP ^8.1 v1.10.1PHP ^8.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/c08758974ce25b9a45a39129aed8e9f643c3bce49542f103cd7b7485b40f9fbb?d=identicon)[blacklabs](/maintainers/blacklabs) --- Top Contributors [![ChaDonSom](https://avatars.githubusercontent.com/u/24794769?v=4)](https://github.com/ChaDonSom "ChaDonSom (165 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (25 commits)") --- Tags cliconsoleblacklabs ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/blacklabs-blacklabs/health.svg) ``` [![Health](https://phpackages.com/badges/blacklabs-blacklabs/health.svg)](https://phpackages.com/packages/blacklabs-blacklabs) ``` ### Alternatives [symfony/console Eases the creation of beautiful and testable command line interfaces 9.8k1.1B11.2k](/packages/symfony-console)[nunomaduro/collision Cli error handling for console/command-line PHP applications. 4.6k331.8M8.4k](/packages/nunomaduro-collision)[nunomaduro/termwind It's like Tailwind CSS, but for the console. 2.5k239.8M282](/packages/nunomaduro-termwind)[wp-cli/php-cli-tools Console utilities for PHP 68325.0M364](/packages/wp-cli-php-cli-tools)[php-school/cli-menu A command line menu helper in PHP 2.0k1.1M27](/packages/php-school-cli-menu)[seld/cli-prompt Allows you to prompt for user input on the command line, and optionally hide the characters they type 24725.8M17](/packages/seld-cli-prompt) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)