How I download files with Capistrano v3

TL;DR

on roles(:backup) do |host|
    download! "backup/backup.tgz", "backup-#{fetch(:host})}.tgz"
end

UPDATE: I've found and started using the SSHKit method download! as well as run_locally as suggested. Since Capistrano V3 sits on SSHKit, this should be a drop in replacement for the way I was using system.

namespace :backup do
    desc "Package a backup file, download it to the local system, and extract locally"
    task "files" do
        on roles(:db) do |host|

            # create the backup somehow on the remote server
            within "/backup" do
                execute :tar, "-czvf backup.tgz path_to_file_to_backup.txt"
            end

            # download the backup file
            on roles(:backup) do |host|
                download! "/backup/backup.tgz", "backup-#{fetch(:host})}.tgz"
            end

            # and unpack the tgz backup file
            run_locally do
                execute :tar, "-xzvf backup-#{fetch(:host})}.tgz"
            end

        end
    end
end

This is the old method with notes. Using system and manually calling scp didn't seem the best way, but it worked. Keeping it here for reference.

namespace :backup do
    desc "Package a backup file, and download it to the local system.""
    task "files" do
        on roles(:db) do |host|
            # create the backup somehow on the remote server
            within "~/backup" do
                execute :tar, "-czvf backup.tgz path_to_file_to_backup.txt"
            end

            # download and unpack the tgz backup file
            # note (bins): currently this requires scp and tar to be
            # available on your local system
            #
            # note (auth): this scp command is assumed to work because
            # you can access the deploy user already via your public/private
            # key, since otherwise 'cap' commands via sshkit would not
            # work it is of course possible that you'll need to tweak
            # this if thats not the case for you
            # system runs commands locally, so here we are just
            # automating the process of fetching a remote file via scp
            #
            # use the variables we have accessible via the cap env to scp
            # remote file to local system
            # file name would be in this case something like
            # "backup-example.com.tgz" if the :host was example.com
            system("scp #{fetch(:deploy_user)}@#{host}:~/backup.tgz backup-#{fetch(:host})}.tgz")

            # furthermore, you could run commands locally to unpack
            # or move the file into location
            system("tar -xzvf -#{fetch(:host})}")
            system("rm -f -#{fetch(:host})}")
            system("mv -f path_to_file_to_backup.txt data/backup/backup.txt")
        end

    end
end