Airbrussh: the log formatter behind Capistrano's deploy output

The formatter you already have

Airbrussh is a concise log formatter for Capistrano and SSHKit. It displays well-formatted, useful log output that is easy to read, and it also saves Capistrano's verbose output to a separate log file just in case you need additional details for troubleshooting.

The fact that most people have it without knowing it is stated plainly in the README. As of April 2016, Airbrussh is bundled with Capistrano 3.5 and is Capistrano's default formatter. There is nothing additional to install or enable. If you have upgraded to Capistrano 3.5 since 2016, you have been using this library every time you deploy.

The problem it addresses is that a default Capistrano run is noisy. Deployment output is a stream of SSH commands, their output, and the surrounding machinery, and the useful signal, which task is running and which one is slow, is buried in it. Airbrussh reformats that stream into something a human can read while a deploy is happening.

The audience is therefore mostly existing Capistrano users who want to change or extend the output, plus anyone using SSHKit directly, which is the lower-level library Capistrano is built on. The homepage is the author's blog, and the README points at a blog post, Introducing Airbrussh, for the reasoning behind the design and for a walkthrough of how exactly it changes Capistrano's output.

The project is MIT licensed, written in Ruby, and the last push was on 2026-10-01 with release v1.6.2 from 2026-07-12.

What the formatter shows and what it hides

The displayed set is short and specific. You get the name of the Capistrano task being executed, and when each task started, given as minutes and seconds elapsed since the deploy began. You get the SSH command-line strings that are executed, and for tasks that run multiple commands the numeric prefix indicates the command in the sequence, starting from 01. You get stdout and stderr output from each command, and the duration of each command execution per server.

The per-command duration is the part that changes how you work. A deploy that takes four minutes tells you nothing; a deploy where one command on one server took fifty seconds tells you where to look.

What is not displayed is equally deliberate. Airbrussh omits Capistrano's test commands, which can be noisy and confusing, and it hides things like environment variables as well as cd and env invocations. For brevity, the point is that the interesting part of a deploy is the work, not the shell plumbing around it.

The consequence is that Airbrussh is not an audit trail. The README is direct about where the full record lives: to see a full audit of Capistrano's execution, including exactly what commands were run on each server, look at log/capistrano.log.

That split is the design. The screen shows the summary, the file holds the record. It also means a debugging session starts in the log file rather than in the terminal, which is a habit change for people used to scrolling back through a deploy in their shell.

Configuring the formatter through format_options

In Capistrano 3.5 and newer the configuration goes through the :format_options variable, and the README gives this example:

# Pass options to Airbrussh
set :format_options, color: false, truncate: 80

The option table is the real reference, and the defaults listed are the ones used by Capistrano 3.5.

The banner option takes a string such as Capistrano started! that is printed when Capistrano starts up, and it defaults to nil. The color option takes true or false for ansi color, and its default is :auto, in which case Airbrussh uses color based on whether the output is a TTY or whether the SSHKIT_COLOR environment variable is set. That auto behaviour is what makes the same deploy readable on a terminal and sane in a CI log.

The command_output option controls what SSH output you see. It can be :stdout, :stderr or true, meaning both, and its default is true. Setting it to false gives a minimal look with no SSH output at all.

The truncate option sets a width limit in characters, or false to disable truncation, and it defaults to :auto, which truncates to the width of the terminal window if that can be determined. The task_prefix option takes a string to prefix to task output, described as handy for output collapsing in the style of buildkite's --- prefix, and it defaults to nil.

The log_file option defaults to log/capistrano.log, which is where Capistrano's verbose output is saved to facilitate debugging, and setting it to nil disables that entirely.

The context option is the one aimed at other users of the library. It defines the execution context and is targeted towards uses of Airbrussh outside of Rake and Capistrano, with alternate implementations expected to provide current_task_name, register_new_command and position.

Enabling it manually and using it with SSHKit

Airbrussh is enabled by default in Capistrano 3.5 and newer, and to enable it manually, for example when upgrading an existing project, you set the Capistrano format in deploy.rb:

# In deploy.rb
set :format, :airbrussh

That one line is the whole manual enablement. If you are not yet using Capistrano 3.5, or you wish to use Airbrussh with SSHKit directly, the advanced and legacy usage section covers installation.

For SSHKit users, the gem is added with require set to false, so it is not loaded by Bundler automatically and you control when it loads:

gem "airbrussh", require: false

You then run bundle, and add the require to your application's Capfile:

require "airbrussh/capistrano"

The require: false detail is not cosmetic. Bundler auto-requiring a formatter gem at boot would install its hooks before you have decided to use them, and the Capistrano 3.4.x path needs the require to happen at a specific point rather than at load.

There is one trap in the legacy path that the README calls out as important. Explicitly setting Capistrano's :format option in your deploy.rb will override airbrussh, so if you have set :format to :pretty you must remove that line. Capistrano 3.4.x also does not have the :format_options configuration system, so on that version you configure Airbrussh with the block form instead:

Airbrussh.configure do |config|
  config.color = false
  config.command_output = true
  # etc.
end

The supported matrix is stated as Airbrussh having been tested with MRI 1.9+, Capistrano 3.4.0+ and SSHKit 1.6.1+.

JRuby, Capistrano 2 and missing output

The FAQ covers three specific problems, and the JRuby one is the most interesting.

JRuby is not officially supported or tested, but may work. You must disable automatic truncation to work around a known bug in the JRuby 9.0 standard library, which means setting truncate to false:

set :format_options, truncate: false

A library whose JRuby support depends on turning off a feature is telling you something about the platform assumptions, and the auto truncation depends on determining the terminal width, which is exactly the sort of thing a non-POSIX standard library handles differently.

Capistrano 2 is a harder no. The answer is that Capistrano 3 is required, with a recommendation of Capistrano 3.4.0 or higher, and that 3.5.0 and higher have Airbrussh enabled by default with no installation needed. Capistrano 3.4.x is also supported, with installation instructions.

The third FAQ entry is the one you will hit first if something is wrong. If Airbrussh is not displaying the output of your commands, for example you run tail in one of your Capistrano tasks and nothing shows, the fix is to make sure Airbrussh is configured to show SSH output:

set :format_options, command_output: true

That option defaults to true, so the more common cause of the symptom is that a deployment is setting format_options with a partial hash and overriding the default rather than merging with it. Setting the option explicitly is the remedy either way.

Editorial conclusion

Adopt Airbrussh if you run Capistrano 3.4 or newer and want deploy output that is readable at a glance, or you use SSHKit directly and want the same formatter. Do not adopt it for Capistrano 2, which is not supported, and do not expect it to be a full audit trail, since it deliberately hides commands and keeps the complete record in log/capistrano.log instead. Verify first that your Capistrano version is 3.4.0 or higher, that you are not overriding the :format option in deploy.rb, and that the truncate setting matches your terminal width if the output is being cut off.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mattbrictson/airbrussh on GitHub
4. README
5. Releases