The Pagoda CLI

Last Updated October 2014

The “pagoda” command-line client is a tool designed to improve your workflow on Pagoda Box. It provides app creation, remote service connections, log management, and more – all from the command line. The Terminal Ranger’s creed: Why use mice when keyboards suffice? This doc covers what commands are available in the terminal client and how to use them. After reading it, you should be familiar with:

  • Using the Pagoda CLI
  • Managing apps from the command line
  • Basking in your CLI-enhanced workflow

Download & Install the CLI

Visit our downloads page for download links and instructions for installing the Pagoda CLI.

Using the v1 and v2 CLIs at the Same Time

If you still need to use the v1 pagoda cli, you’ll need to change the name of your v1 cli executable. This can be done by simply changing the name of the v1 executable file. To call the v1 cli, use the new executable filename instead of "pagoda". Use "pagoda" to call the v2 cli.

Command Summary

Command : Description
tunnel : Remotely connect to a service
log : Print or stream app logs
run : Remotely run a command on a code service
ssh : Open an SSH connection to a service
open : Open the dashboard of an app
create : Create an application
list : List all your applications
info : Display info about an application
rebuild : Rebuild and redeploy an app
rollback : Roll an app back one deploy
destroy : Destroy an app
evar:create : Create an environment variable
evar:list : List an app's environment variables
evar:destroy : Remove an environment variable
service:list : List an app's services
service:info : List info about a service
service:restart : Restart a service
service:reboot : Reboot a service
service:repair : Repair a service
user : Display your user’s information
switch : Switch user accounts
update : Update the CLI
Global Options
-h, --help : View detailed information about a command
-v, --version : Show the installed version of the CLI
--debug : Show all API requests/responses (Must appear last)

Tunnel Into a Data Service

The “tunnel” command sets up an SSH port-forward from your local machine, allowing you to securely connect to and manage data within data services from your local machine.

Using pagoda tunnel Terminal

  # Pattern
  $ pagoda tunnel [-a app-name] service-name/UID [-p port] [-i /path/to/file]
  $ pagoda tunnel [-a app-name] service-name/UID [-p port] [--indentity-file=/path/to/file]
   
  # Examples
  $ pagoda tunnel -a app-name database1 -p 3306
  $ pagoda tunnel database1 -i ~/.ssh/id_rsa.pub

Once the tunnel is open, use the credentials provided in the output to remotely connect to your service using a local client.

Options

-a, --app
Specify the app, by name or ID, which includes the service into which you’d like to tunnel. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

-p, --port
Specify which local port to forward to your data service. If no port is provided, the default port of each service type is assumed.

Examples:

mysql     : 3306 
mongodb : 27017
redis : 6379
memcached : 11211

The tunnel will not detect if the port is already in use. If it is, the tunnel command and/or connections through the tunnel will fail.

-i, --indentity-file
Specify the file path to which SSH key should be used to authenticate access to the data service. This must be the absolute path to the public key file on your local machine

View & Stream App Logs

The “log” command allows you to view and or stream your application logs.

Using pagoda log Terminal

  # Pattern
  $ pagoda log [-a app-name] [-c count] [-l]
  $ pagoda log [--app=app-name] [--count=100] [--live]
   
  # Examples
  $ pagoda log
  $ pagoda log -a app-name -c 500
  $ pagoda log -a app-name -l

Options

b>-a, --app
Specify the app, by name or ID, whose log you’d like to view. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

-c, --count
Specify the number of log entries to load. If no count is provided, the last 100 log entries will be loaded.

-l, --live
Stream application logs.

Remotely Run a Command on a Code Service

The “run” command runs a specified command on a code service within an app. “Complex” commands must be formatted inside single quotes (' ‘).

Using pagoda run Terminal

  # Pattern
  $ pagoda run [-a app-name] [-s service-name/UID] 
  $ pagoda run [--app=app-name] [--service=service-name/UID] 
   
  # Example
  $ pagoda run ‘ls -ln’
  $ pagoda run -a app-name -s web1 ‘ls -ln’

Options

-a, --app
Specify the app, by name or ID, which includes the service on which you’d like to run the command. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

-s, --service
Specify the code service on which to run the command. If no service is specified, the command will run on an instance of the first detected code service.

-i, --indentity-file
Specify the file path to which SSH key should be used to authenticate access to the code service. This must be the absolute path to the public key file on your local machine.

SSH Into a Service

The “ssh” command opens an SSH connection to an app’s service, allowing you to run commands directly on the service. Native prompts are available for web, worker, & network storage services but not for databases and caches. To interact with these services, you should use the tunnel command.

Using pagoda ssh Terminal

  # Pattern
  $ pagoda ssh [-a app-name] service-name/UID
  $ pagoda ssh [--app=app-name] service-name/UID
   
  # Examples
  $ pagoda ssh -a app-name web1
  $ pagoda ssh -i ~/.ssh/id_rsa.pub web1

Options

-a, --app
Specify the app, by name or ID, which includes the service to which you’d like to open an SSH connection. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

-i, --indentity-file
Specify the file path to which SSH key should be used to authenticate the SSH connection. This must be the absolute path to the public key file on your local machine.

Open the Dashboard of an App

The "open" command opens the dashboard of a specific app in your local OS's default browser.

Using pagoda open Terminal

  # Pattern
  $ pagoda open [-a app-name] [-p path]
  $ pagoda open [--app=app-name] [--path=path]
    
  # Examples
  $ pagoda open -a app-name
  $ pagoda open -a app-name -p /invoices

Options

-a, --app
Specify the app, by name or ID, whose dashboard you would like to open. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

-p, --path
Specify the url path or page of the dashboard you would like to open.


Create an App

The “create” command creates an application on Pagoda Box.

Using pagoda create Terminal

  # Pattern
  $ pagoda create [-a app-name] [-t]
  $ pagoda create [--app=app-name] [--tinker]
   
  # Examples
  $ pagoda create
  $ pagoda create -a app-name -t

Options

-a, --app
Specify the name of the created app. If no app-name is specified, it will be auto-generated by Pagoda Box.

-t, --tinker
Create the app as a tinker app. If tinker is not specified, the app will be created as a production app.

View a List of Your Apps

The “list” command lists all apps associated with the currently logged in user, your the app’s current states, and shows your collaborative role for each. To view the key of app states, pass the “-h” flag.

Using pagoda list Terminal

  $ pagoda list

View an App’s Information

The “info” command lists information about your app including things such as the app’s git clone URL, the currently deployed commit, team members, etc.

Using pagoda info Terminal

  # Pattern
  $ pagoda info [-a app-name]
  $ pagoda info [--app=app-name]
   
  # Examples
  $ pagoda info
  $ pagoda info -a app-name

Options

-a, --app
Specify the app, by name or ID, that you’d like to view the info. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

Rebuild an App’s Code Services

The “rebuild” command rebuilds all of an app’s code services.

Using pagoda rebuild Terminal

  # Pattern
  $ pagoda rebuild [-a app-name]
  $ pagoda rebuild [--app=app-name]
   
  # Examples
  $ pagoda rebuild
  $ pagoda rebuild -a app-name

Options

-a, --app
Specify the app, by name or ID, that you’d like to rebuild. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

Rollback an App’s Code Services

The “rollback” command rolls an app’s code services back one deploy.

Using pagoda rollback Terminal

  # Pattern
  $ pagoda rollback [-a app-name]
  $ pagoda rollback [--app=app-name]
   
  # Examples
  $ pagoda rollback
  $ pagoda rollback -a app-name

Options

-a, --app
Specify the app, by name or ID, that you’d like to rollback. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

Destroy an App

The “destroy” command deletes an app from Pagoda Box. Only application owners can delete an app. This cannot be undone.

Using pagoda destroy Terminal

  # Pattern
  $ pagoda destroy [-a app-name] [-f]
  $ pagoda destroy [--app=app-name] [--force]
   
  # Examples
  $ pagoda destroy
  $ pagoda destroy -a app-name

Options

-a, --app
Specify the app, by name or ID, that you’d like to destroy. If no app is provided, the CLI will prompt for an app-name/ID.

-f, --force
Force the deletion of an app with no confirmation.


Create an Environment Variable

The "evar:create" command allows you to add environment variables to your app from the command line.

Using pagoda evar:create Terminal

  # Pattern
  $ pagoda evar:create [-a app-name] KEY=VALUE
  $ pagoda evar:create [--app=app-name] KEY=VALUE
   
  # Examples
  $ pagoda evar:create ENV=production
  $ pagoda evar:create -a app-name ENV=production

The KEY=VALUE string is split on the =, so neither the KEY nor the VALUE can contain an "=". Other restrictions are that KEYs cannot begin with a number or contain hyphens.

Options

-a, --app
Specify the app, by name or ID, to which you’d like to add an environment variable. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

List an App's Environment Variables

The "evar:list" command lists all environment variables associated with an app. It lists both custom environment variables as well as auto-generated environment variables.

Using pagoda evar:list Terminal

  # Pattern
  $ pagoda evar:list [-a app-name]
  $ pagoda evar:list [--app=app-name]
   
  # Examples
  $ pagoda evar:list
  $ pagoda evar:list -a app-name

Options

-a, --app
Specify the app, by name or ID, whose environment variables you’d like listed. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

Remove an Environment Variable

The "evar:destroy" command removes an environment variable. Pass the KEY of the Environment Variable key-value pair you'd like to destroy.

Using pagoda evar:destroy Terminal

  # Pattern
  $ pagoda evar:destroy [-a app-name] KEY
  $ pagoda evar:destroy [--app=app-name] KEY
   
  # Examples
  $ pagoda evar:destroy PLATFORM
  $ pagoda evar:destroy -a app-name PLATFORM

Options

-a, --app
Specify the app, by name or ID, from which you'd like the environment variable to be removed. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.


List Services Within an App

The “service:list” command lists services within an app.

Using pagoda service:list Terminal

  # Pattern
  $ pagoda service:list [-a app-name]
  $ pagoda service:list [--app=app-name]
   
  # Examples
  $ pagoda service:list
  $ pagoda service:list -a app-name

Options

-a, --app
Specify the app, by name or ID, whose services you would like listed. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

View a Service’s Information

The “service:info” command provides information about a services including its current status, scale, connection credentials, etc.

Using pagoda service:info Terminal

  # Pattern
  $ pagoda service:info [-a app-name] service-name/UID
  $ pagoda service:info [--app=app-name] service-name/UID
   
  # Examples
  $ pagoda service:info database1
  $ pagoda service:info -a app-name database1

Options

-a, --app
Specify the app, by name or ID, whose service you would like information about. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

Restart a Service

The “service:restart” command restarts all of the running processes on a service's instance(s).

Using pagoda service:restart Terminal

  # Pattern
  $ pagoda service:restart [-a app-name] service-name/UID
  $ pagoda service:restart [--app=app-name] service-name/UID
   
  # Examples
  $ pagoda service:restart web1
  $ pagoda service:restart -a app-name web1

Options

-a, --app
Specify the app, by name or ID, that contains the service you would like to restart. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

Reboot a Service

The “service:reboot” command shuts down and reboots a service's instance(s), recovering each of the service's processes.

Using pagoda service:reboot Terminal

  # Pattern
  $ pagoda service:reboot [-a app-name] service-name/UID
  $ pagoda service:reboot [--app=app-name] service-name/UID
   
  # Examples
  $ pagoda service:reboot web1
  $ pagoda service:reboot -a app-name web1

Options

-a, --app
Specify the app, by name or ID, that contains the service you would like to reboot. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.

Repair a Service

The “service:repair” command provisions new instances based on settings in your Boxfile. For code services, the currently deployed commit is used to create the new instance(s). For data services, all data is migrated to the new instance (if possible).

Using pagoda service:repair Terminal

  # Pattern
  $ pagoda service:repair [-a app-name] service-name/UID
  $ pagoda service:repair [--app=app-name] service-name/UID
   
  # Examples
  $ pagoda service:repair web1
  $ pagoda service:repair -a app-name web1

Options

-a, --app
Specify the app, by name or ID, that contains the service you would like to repair. If no app is provided, the CLI will attempt to detect it by analyzing git remotes. If no app or multiple apps are detected, the CLI will prompt for an app-name/ID.


View User Information

The “user” command displays information about the currently logged in user.

Using pagoda user Terminal

  $ pagoda user

Switch User Accounts

The “switch” command allows you to switch between Pagoda Box user accounts on the fly.

Using pagoda switch Terminal

  # Pattern
  $ pagoda switch [-u username] [-p password]
  $ pagoda switch [--user=username] [--password=password]
   
  # Examples
  $ pagoda switch
  $ pagoda switch -u username -p password

Options

-u, --user
Specify the username of the account to which you’d like to switch. If no username is provided, the CLI will prompt for one.

-p, --password
Specify the password of the account to which you’d like to switch. If no password is provided, the CLI will prompt for one.

Update the CLI

The "update" command allows you to manually check for and download updates to the Pagoda CLI.

Using pagoda update Terminal

  $ pagoda update

If you have any questions, suggestions, or corrections, let us know.