Terminal CLI Companion Reference

Installing the CLI Companion & Shell Setup

Stratos provides a native command-line companion (stratos) and manages isolated PHP binaries in your user library. To enable the stratos command and prioritize Stratos PHP across all terminal sessions, add the following to your ~/.zshrc (or ~/.zprofile / ~/.bashrc):

# Stratos CLI & PHP PATH
export PATH="$HOME/bin:$HOME/Library/Application Support/Stratos/bin:$PATH"

After saving your configuration file, reload your current shell:

source ~/.zshrc

PHP CLI Version Management

1. Switch the Global PHP Version (stratos use)

You can switch the default php binary used by your terminal at any time:

stratos use 8.4
php -v  # Shows PHP 8.4.x

stratos use 8.3
php -v  # Shows PHP 8.3.x

This automatically updates the php symlink in ~/Library/Application Support/Stratos/bin/php to the selected PHP runtime.

2. Versioned PHP Commands (Herd-Style)

If you work across multiple projects requiring different PHP versions simultaneously, you can run version-specific commands directly without changing the global default:

• php85 -v — Execute PHP 8.5
• php84 -v — Execute PHP 8.4
• php83 -v — Execute PHP 8.3
• php82 -v — Execute PHP 8.2
• php81 -v — Execute PHP 8.1
• php74 -v — Execute PHP 7.4

3. Direct Execution via Stratos

You can also execute scripts, Composer, and Artisan commands directly using the active Stratos runtime without worrying about system PATH conflicts:

stratos php script.php
stratos composer install
stratos artisan migrate

CLI Command Reference

Command	Description
stratos use <version>	Switch global CLI PHP runtime version (e.g. stratos use 8.4 or stratos use 8.3).
stratos php [args]	Execute PHP using the active Stratos isolated runtime.
stratos composer [args]	Execute Composer using the active Stratos PHP environment.
stratos artisan [args]	Execute php artisan in the current project directory.
stratos list	List all detected local sites and assigned PHP versions.
stratos open <site>	Open the site in your default web browser over HTTPS.
stratos reveal <site>	Reveal the site's project folder in macOS Finder.
stratos logs [name] [-f]	Tail live Nginx, PHP-FPM, or Dump log streams in your terminal (nginx, php, dump).
stratos status	Display JSON status of all active services, ports, and webroot.
stratos test [options]	Run automated test suite (--filter <name>, --json, --list).
stratos install	Symlink the CLI binary to ~/bin/stratos.
stratos uninstall	Remove the ~/bin/stratos symlink.

Troubleshooting CLI Version Mismatches

If running php -v outputs an unexpected version (e.g., Homebrew or macOS system PHP) instead of Stratos PHP:

1. Ensure ~/Library/Application Support/Stratos/bin is at the beginning of your $PATH in ~/.zshrc, before /opt/homebrew/bin.
2. Run source ~/.zshrc to apply changes to the active terminal window.
3. Run which php to verify that it resolves to .../Stratos/bin/php.