Posted over 6 years ago. Visible to the public. Repeats. Linked content.

How to use the Capistrano 2 shell to execute commands on servers

Capistrano 2 brings the shell command which allows you to run commands on your deployment targets.
There is also invoke to run a command directly from your terminal.

Both commands allow running Capistrano tasks or shell commands, and scope to individual machines or machine roles.

Unfortunately Capistrano 3 does not include these commands any more.

cap shell


First of all, spawn a Capistrano shell (we're using the multistage extension here):

$ cap staging shell

In your "cap" shell you can now run Capistrano tasks by prepending an exclamation mark. For example:

cap> !deploy:revision ** [out ::] 9aeed9030db6a7b5b4ba077337545677b4fd5c22 ** [out ::] 9aeed9030db6a7b5b4ba077337545677b4fd5c22 ** [out ::] 9aeed9030db6a7b5b4ba077337545677b4fd5c22

(deploy:revision is a custom task to check the deployed revision)

To run shell commands on each machine, simply put them there as if you were on a regular terminal session:

cap> uname -o ** [out ::] GNU/Linux ** [out ::] GNU/Linux ** [out ::] GNU/Linux

Running more than one shell command

Be aware that shell commands will be sent once, and that your shell on the remote machine is not persistent:

cap> cd /tmp cap> pwd ** [out ::] /home/deploy ** [out ::] /home/deploy ** [out ::] /home/deploy

Instead, queue them:

cap> cd /tmp && pwd ** [out ::] /tmp ** [out ::] /tmp ** [out ::] /tmp

Running commands only on individual machines

You may have some commands that you want to run only on a subset of machines, e.g. machines running queue workers.

To pick machines by name, use the on keyword:

cap> on uname -o ** [out ::] GNU/Linux

Join multiple machine names with commas (e.g.,

The above is a bit impractical (you could just SSH to a single machine), but you can also scope to entire role groups using the with keyword:

cap> with web uname -o ** [out ::] GNU/Linux ** [out ::] GNU/Linux
cap> with queue uname -o ** [out ::] GNU/Linux

For more information, see the linked page.

cap invoke

To run shell commands on all servers, you can also use Capistrano's invoke. Its syntax is a bit more complicated:

$ cap staging invoke COMMAND='uname -o' ** [out ::] GNU/Linux ** [out ::] GNU/Linux ** [out ::] GNU/Linux

Note the COMMAND environment variable which must hold the command(s) you want to run.
As mentioned above, if you want to run multiple commands, you need to chain them:

$ cap staging invoke COMMAND='cd /tmp && pwd' ** [out ::] /tmp ** [out ::] /tmp ** [out ::] /tmp

Note that you probably should not use these commands for complex shell operations.
Instead, maybe create a file that does things for you and run that one instead. Or try an application like Terminator that allows sending the same keystrokes to multiple machines.

makandra has been working exclusively with Ruby on Rails since 2007. Our laser focus on a single technology has made us a leader in this space.

Owner of this card:

Arne Hartherz
Last edit:
8 months ago
by Judith Roth
About this deck:
We are makandra and do test-driven, agile Ruby on Rails software development.
License for source code
Posted by Arne Hartherz to makandra dev
This website uses cookies to improve usability and analyze traffic.
Accept or learn more