Login Try it Free

The Pagoda Terminal Client

Last Updated: May 29, 2013 03:28PM MDT

The Terminal Ranger’s creed: Why use mice when keyboards suffice? Sometimes even an elegant interface isn’t your cup of tea. Well lucky for you, we have written a rock solid command line application that lets you create, deploy, rollback, securely connect to your live database, etc... After reading this guide, you should be able to:

  •  Install the Pagoda Terminal Client
  •  Manage your Pagoda Box apps from your command line
  •  Enjoy the awesomeness of a streamlined app management workflow
 

Installing the Terminal Client

The Pagoda Box Terminal Client is a rubygem so installation is pretty simple. First off, you need to have Ruby installed. Installation is different for each operating system.

Mac

Ruby and RubyGems come pre-installed on Mac OSX. As long as you are running v10.5 or later, you should be good to go.

Windows

There are a couple of different ways to install Ruby in Windows. We have found the easiest way is to use this auto-installer. If this doesn’t work for you, a google search will give you a pretty good list of installation walk-throughs.

Linux

Just use your preferred package manager to download the Ruby package. For Ubuntu users, the gem is available through getdeb.net

Once Ruby is installed, simply run the following command to install the Pagoda RubyGem:

 TerminalInstall the Pagoda Gem 

Using the Terminal Client

The majority of the information covered in the following section can quickly be referenced using the “pagoda help” command.

The first time you use the Pagoda Terminal Client, you will be asked for a username and password. Use your Pagoda Box username and password. You will only have to do this once. Once you are logged in, you are ready to go.

Just as with other command line clients, all commands specific to the Pagoda terminal client must be prefaced by “pagoda”.

Commands

clone Clones an application from Pagoda Box
create Creates a new application on Pagoda Box
deploy Deploys your code to your live Pagoda Box app
destroy Removes your application
help Shows lists of possible commands associated to a particular command
info Shows information about your app
init Connects your local repo with your Pagoda Box repo
initconfig Initializes the config file using current global options. If you need to change the Pagoda Box username and password associated with your gem, you can do it here.
key:gen Generates an ssh key and posts it to Pagoda Box
key:push Posts an existing ssh key to Pagoda Box
list Lists your apps on Pagoda Box
log Outputs an aggregated stream of application logs
rename Renames your application
rollback Rolls your app back to the previously deployed commit
tunnel Tunnels to a component in your application

Parameters

Global:

-a <name> | --app=<name>
Set the application name (Only necessary when not in repo dir).

-u <username> | --username=<username>
When set, will not attempt to save your username. Also over-rides any saved username.

-p <password> | --password=<password>
When set, will not attempt to save your password. Also over-rides any saved password.

-f
Executes all commands without confirmation request.

Deploying - pagoda deploy :

-b <branch> | --branch=<branch>
Specify the branch name. By default uses the branch your local repo is on.

-c <commit> | --commit=<commit>
Specify the commit id. By default uses the commit HEAD is set to.

Tunneling - pagoda tunnel :

-c <component_name> | --component=<component_name>
Specify the component you want to tunnel to.

Logs - pagoda log :

-c <number> | --count=<number>
Sets the number of log entries returned.

-l | --live
Outputs a live stream or your aggregated application logs.

Launching an App

To launch an app, you must be inside the root directory of your repo. Use the following command:

 TerminalLaunch an App 

This will automatically create a repo on Pagoda Box and attach a "pagoda" remote. Your Pagoda Box repo is then pushed live. If you already have a remote named "pagoda," it will allow you to name your new remote.

Cloning an App from Pagoda Box

To clone an app from a Pagoda Box, you must be an owner or collaborator of that app. Simply use the following command:

 TerminalCloning an App from Pagoda Box 

Deploying Commits

To deploy the current state of your local instance while inside your repo:

 TerminalDeploy While Inside Your Repo 

If you’re outside of your repo, just specify which repo you would like to deploy:

 TerminalDeploy While Outside Your Repo 

You are also able to specify which branch to deploy:

 TerminalSpecify a Branch to Deploy 

Or even specify a commit:

 TerminalSpecify a Commit to Deploy 

Rolling Back

The ability to quickly rollback code is a nice tool for any developer to have in their tool-belt. Using the rollback command will roll your app back to the previously deployed commit. If you’re inside your repo, use the following command:

 TerminalRollback While Inside Repo 

If you’re outside of your repo, you simply need to specify which app you would like to roll back:

 TerminalRollback While Outside Repo 

Connecting Your Local Repo to an Existing App

While inside your repo, run the following command to connect to an existing app on Pagodabox.

 TerminalConnecting Your Local Repo to an Existing App 

This automatically creates a "pagoda" remote associated to the git clone address with the specified app. If your repo already has a "pagoda" remote, you will be able to name the new remote.

Destroying an App

Destroying an app is really simple. If you’re inside your repo, just use the following command:

 TerminalDestroy an App While Inside Repo 

You will be asked to confirm whether or not you really want to destroy your app. If you want to skip the confirmation, just append the “-f” parameter to the previous command. This will force the command without any confirmation.

If you are not inside your app’s repo, you can still destroy it but you need to specify the app you would like to destroy:

 

 TerminalDestroy an App While Outside Repo 

Managing SSH Keys

For some transactions, we need your public SSH Key. There's a couple of ways you can get it to us.

 TerminalPosting Your Existing SSH Key to Pagoda Box 

You can also generate a new public SSH key and push it to Pagoda Box by using the following command:

 TerminalGenerating a New SSH Key and Posting it to Pagoda Box 

Creating a Database Tunnel

This functionality is so awesome we decided to give it its own guide. Check out the Creating a Secure Database Tunnel from Your Desktop Guide.

Viewing Application Logs

This functionality is covered in the Log Management guide.

Pagoda in Your Workflow

The goal of the Pagoda Terminal Client is to make your code deployment workflow as frictionless as possible. You can still deploy new apps and commits, rollback, or scale your app using the Pagoda Box Admin Panel, but that can break up your workflow. Using the terminal client, you can do all these things in the same place you’re managing your git repo, so you’re workflow is as uninterrupted as possible.

Here’s an example:

 TerminalExample: Pagoda Terminal Workflow 

In this example, a new app was created, launched, code was changed, added, committed,and deployed to the live instance on Pagoda Box, rolled back, and destroyed all from a command line, in under 2 minutes.

If you have any suggestions or corrections for this guide, please submit a ticket.

Contact Us