I spent a little time working with Terminus due to a project that was recently moved over to Pantheon. Terminus is still very new, but the roadmap looks promising. This type of forward thinking is what's needed to comfortably integrate ops with managed services.

I'm going to take you through a few of the commands that oriented me to the API, and then the process to work out a friendly solution for downloading the latest backup (code, database, or files), from any environment.

After installing terminus via the readme in the GitHub repo, and clearing cache, first you need to login:

First you need to authenticate

$ drush pauth
Pantheon account email address: [email protected]
Pantheon dashboard password: xxxxxx
Authenticating as [email protected]                                                 [ok]
Success!                                                                          [ok]

If you don't have your UUID handy, you can get a list of sites, with the UUIDs listed

$ drush psites
 Site     Service Level  UUID                                 
 mysite  enterprise     abcdefgh-abcdefghi-abcdefghijklmnopq

Now that you have the UUID, you can request a list of your backups. The first argument is your UUID and the second is the environment. (dev/test/live)

$ drush psite-backups site-uuid dev
 Type    Date                           Element   Bucket                Size     
 export  Mon, 26 Aug 13 08:43:16 +0000  files     1234504000_automated  14.5 MB  
 export  Mon, 26 Aug 13 08:47:12 +0000  database  1234504000_automated  7.45 MB  
 export  Mon, 26 Aug 13 08:48:13 +0000  code      1234504000_automated  82.86 MB 
 export  Sun, 25 Aug 13 08:37:27 +0000  files     1234417600_automated  14.5 MB  
 export  Sun, 25 Aug 13 08:42:04 +0000  database  1234417600_automated  7.49 MB  
 export  Sun, 25 Aug 13 08:43:15 +0000  code      1234417600_automated  82.84 MB 
 export  Sat, 24 Aug 13 08:37:08 +0000  files     1234331200_automated  14.5 MB  
 export  Sat, 24 Aug 13 08:41:17 +0000  database  1234331200_automated  7.64 MB  
 export  Sat, 24 Aug 13 08:42:06 +0000  code      1234331200_automated  82.74 MB 
 backup  Sat, 24 Aug 13 07:02:56 +0000  files     1234327675_backup     14.5 MB  
 backup  Sat, 24 Aug 13 07:01:42 +0000  database  1234327675_backup     7.33 MB  
 backup  Sat, 24 Aug 13 07:02:16 +0000  code      1234327675_backup     82.71 MB

Great, now to get a download link, we need to povide the bucket and element from a row in this list, in addition to the uuid and environment, to psite-get-backup.

$ drush psite-get-backup site-uuid dev 1377504000_automated database
Signed url for the backup:
https://pantheon-backups.s3.amazonaws.com/site-uuid/dev/1234504000_automated/mysite_dev_2013-08-26T08-00-00_database.sql.gz?Signature=ABCDEFGmIIBXTEWERe1Ius%3D&Expires=1234568137&AWSAccessKeyId=ABCDEFGHIJKLMNOPQRS

From here, you can copy & paste the URL in your browser, or download it with curl. I wanted to download it with curl.

$ curl --compress -o dev.tar.gz https://pantheon-backups.s3.amazonaws.com/site-uuid/dev/1234504000_automated/mysite_dev_2013-08-26T08-00-00_database.sql.gz?Signature=ASDFFSDFMIe%2BopQX1Ius%3D&Expires=1234568137&AWSAccessKeyId=ABCDEFGHIJKLMNOPQRS

I believe you will need to use --compress, or -L flags for the s3 download to work.

My first attempt at making this into a script I could just execute was to pipe the output of the commands into each other. This was fun to write, but not very fun to look at. :)

$ drush psite-backups site-uuid dev | awk '/database/{print $9, $8}' | head -n1 | xargs drush psite-get-backup site-uuid dev | grep 'https' | xargs curl --compress -o dev.tar.gz

That worked, and with a little more love in converting it into a shell script that accepts arguments for uuid, environment, element, and destination, it would work like a champ.

It would look a lot better if it were built into the same drush API though.

This is how it started out.

$ drush psite-dl-backup site-uuid dev 1234504000_automated database "./"

This still wasn't too cool since we need to copy a big uuid in and call out a bucket specifically... which would require another looking.

I thought it would be nice if a user at the terminal wouldn't need to know anything but the command, so I added a prompt driven workflow to retrieve a backup:

$ drush psite-dl-backup
Select a site.
 [0]  :  Cancel                                                    
 [1]  :  mysite  enterprise  site-uuid
1
Select an environment.
 [0]  :  Cancel 
 [1]  :  dev    
 [2]  :  test   
 [3]  :  live
1
Backup type.
 [0]  :  Cancel   
 [1]  :  database 
 [2]  :  files    
 [3]  :  code
1
Select a backup.
 [0]  :  Cancel                                                  
 [1]  :  mysite_dev_2013-08-26T08-00-00_database.sql.gz 7.45 MB 
 [2]  :  mysite_dev_2013-08-25T08-00-00_database.sql.gz 7.49 MB 
 [3]  :  mysite_dev_2013-08-24T08-00-00_database.sql.gz 7.64 MB 
 [4]  : mysite_dev_2013-08-24T07-01-15_database.sql.gz 7.33 MB
1
Select a destination [./]: 
Cmd: drush psite-dl-backup  dev 1234504000_automated database "./"

This triggers a download and provides the command to run it again. You can see it still needs a uuid and bucket still.

My last iteration was to make it more friendly by taking your Pantheon site name instead of uuid, and also accept the word "latest" for the latest bucket.

$ drush psite-dl-backup mysite dev latest database ./

Ah, now that feels right, and it's something I can remember!

Here's the pull request: https://github.com/pantheon-systems/terminus/pull/10