Weave Code
Scotty Laravel Package
spatie/scotty
Scotty is a beautiful SSH task runner. Write tasks as plain bash in a Scotty.sh file with annotation comments, and it connects to your remote servers, runs each script, and shows exactly what's happening. Fully compatible with Laravel Envoy.
A beautiful SSH task runner
Frequently asked questions about Scotty
- How do I install spatie/scotty for a Laravel project?
- Scotty ships as a single-file phar, so the preferred install is downloading it: curl the latest release into your project or into /usr/local/bin, then chmod +x and run ./scotty list to verify. You can also install it globally with composer global require spatie/scotty. Because it is a CLI binary rather than a library, you do not add it to your application's composer.json dependencies. Pick one install path per team so everyone runs the same version.
- Is Scotty a drop-in replacement for Laravel Envoy?
- Yes. Scotty is fully compatible with Laravel Envoy, including the Blade parsing Envoy uses, so an existing Envoy.blade.php is usually a near-mechanical swap rather than a rewrite. The annotation style with @servers, @task and @macro will feel familiar to anyone who has written Envoy stories. If your setup relies on features specific to the Blade format, verify them in a pilot before deleting your Envoy file.
- Do I need to composer require spatie/scotty inside my Laravel application?
- No. Scotty is a developer-facing CLI distributed as a phar, not a package you install into an app: there is no service provider, no config file, no container binding and no programmatic API. Install it globally on your PATH or vendor the binary in your repository. That keeps your application's dependency tree and runtime surface untouched.
- How do I define servers, tasks and macros in a Scotty.sh file?
- Scotty.sh is plain bash with annotation comments: @servers [email protected] declares a target, @task on:remote marks a bash function to run there, and @macro deploy pullCode clearCache chains tasks together. Because it is just bash, your editor highlights it for free and there is no new DSL to learn. Run the result with scotty run deploy.
- Does Scotty handle zero-downtime deployments and rollbacks?
- No. Scotty runs commands in place over SSH; it does not manage release directories, symlink switching, atomic rollback, package state or drift detection. If you expect a full deployment platform with zero-downtime releases, Scotty will disappoint you. Use it to orchestrate the commands and keep an atomic release strategy, such as symlinked release folders, inside your task scripts if you need one.
- How does Scotty manage SSH keys and secrets?
- It doesn't. Scotty connects with whatever SSH credentials the machine running it already holds, so key distribution, rotation, least privilege and offboarding remain your responsibility. It makes existing access more disciplined by putting the commands under version control, not more restricted. If long-lived SSH keys on laptops are an audit finding, fix the access model first.
- Can I use my existing Envoy.blade.php, and does the Blade format have full feature parity?
- You can: Scotty ports Envoy's Blade parsing, so a Blade-based task file is a realistic migration path. The catch is that the Blade format does not support @option, so it is not at full parity with Scotty.sh. Pick one canonical format per project and stick with it to avoid surprises, and standardise on Scotty.sh if you need options.
- What happens if a task fails halfway through a Scotty run?
- Because each task is a bash script executed on the remote host, a failure can leave changes partially applied, and Scotty does not roll them back for you. Flags such as --continue and --summary change how a run proceeds and what gets reported, so choose a default behaviour per environment and document it. Make your tasks idempotent where possible so re-running is safe.
- Can I run Scotty from CI or a bastion host instead of my laptop?
- Yes. Scotty is stateless, with no agent, daemon or control plane, so it runs anywhere that has PHP and SSH access to the targets: a laptop, a bastion or a CI runner. Where it executes determines your SSH access pattern, so decide that deliberately rather than by default. Running from CI or a bastion usually gives better auditability than keys on developer machines.
- Is Scotty actively maintained and ready for production use?
- Scotty is a Spatie package on a 1.x release line with steady releases and good documentation, though it has a small contributor base and one primary maintainer, which is a real support-scaling consideration. Version 1.4.4 fixed Blade hooks (@before, @after, @error, @success, @finished) that previously failed silently, so verify hook behaviour explicitly during your pilot. For small Laravel fleets deployed over SSH it is a cheap, low-risk addition; teams that need approvals, audit trails and managed pipelines should look at a hosted platform or a fuller deploy tool instead.
Weaver
How can I help you explore Laravel packages today?