Managing remote tsuru server endpoints

In tsuru, a target is the address of the remote tsuru server. Each target is identified by a label and a HTTP/HTTPS address. The client requires at least one target to connect to, there’s no default target. A user may have multiple targets, but he/she will be able to use only per session.

Add a new target

$ tsuru target-add <label> <target> [--set-current|-s]

Adds a new entry to the list of available targets

Minimum # of arguments: 2

List existing targets

$ tsuru target-list

Displays the list of targets, marking the current.

Other commands related to target:

  • target-add: adds a new target to the list of targets
  • target-set: defines one of the targets in the list as the current target
  • target-remove: removes one target from the list

Set a target as current

$ tsuru target-set <label>

Change current target (tsuru server)

Minimum # of arguments: 1

Removes an existing target

$ tsuru target-remove

Remove a target from target-list (tsuru server)

Minimum # of arguments: 1

Check current version

$ tsuru version

display the current version


Create a user

$ tsuru user-create <email>

Creates a user within tsuru remote server. It will ask for the password before issue the request.

Minimum # of arguments: 1

Remove your user from tsuru server

$ tsuru user-remove

Remove currently authenticated user from remote tsuru server. Since there cannot exist any orphan teams, tsuru will refuse to remove a user that is the last member of some team. If this is your case, make sure you remove the team using team-remove before removing the user.


$ tsuru login

Initiates a new tsuru session for a user. If using tsuru native authentication scheme, it will ask for the password and check if the user is successfully authenticated. If using OAuth, it will open a web browser for the user to complete the login.

After that, the token generated by the tsuru server will be stored in ${HOME}/.tsuru_token.

All tsuru actions require the user to be authenticated (except tsuru login and tsuru version).


$ tsuru logout

Logout will delete the token file and terminate the session within tsuru server.

Change user’s password

$ tsuru change-password

Changes the password of the logged in user. It will ask for the current password, the new and the confirmation.

Resets user’s password

$ tsuru reset-password <email> [--token|-t <token>]

Resets the user password.

This process is composed of two steps:

  1. Generate a new token
  2. Reset the password using the token

In order to generate the token, users should run this command without the –token flag. The token will be mailed to the user.

With the token in hand, the user can finally reset the password using the –token flag. The new password will also be mailed to the user.

Minimum # of arguments: 1

Show current valid API token

$ tsuru token-show

Shows API token for the user. This token allow authenticated API calls to tsuru and will never expire. This is useful for integrating CI servers with tsuru.

The key will be generated the first time this command is called. See tsuru token-regenerate if you need to invalidate an existing token.

Regenerate API token

$ tsuru token-regenerate

Generates a new API token. This invalidates previously generated API tokens.

Team management

Create a new team

$ tsuru team-create <teamname>

Create a team for the user. tsuru requires a user to be a member of at least one team in order to create an app or a service instance.

When you create a team, you’re automatically member of this team.

Minimum # of arguments: 1

Remove a team from tsuru

$ tsuru team-remove <team-name>

Removes a team from tsuru server. You’re able to remove teams that you’re member of. A team that has access to any app cannot be removed. Before removing a team, make sure it does not have access to any app (see “app-grant” and “app-revoke” commands for details).

Minimum # of arguments: 1

List teams current user is member

$ tsuru team-list

List all teams that you are member.

Add a user to a team

$ tsuru team-user-add <teamname> <useremail>

Adds a user to a team. You need to be a member of the team to be able to add another user to it.

Minimum # of arguments: 2

Remove a user from a team

$ tsuru team-user-remove <teamname> <useremail>

Removes a user from a team. You need to be a member of the team to be able to remove a user from it.

Minimum # of arguments: 2

List members of a team

$ tsuru team-user-list <teamname>

List members of a team.

Minimum # of arguments: 1


Guessing application names

Some application related commands that are described below have the optional parameter -a/--app, used to specify the name of the application.

If this parameter is omitted, tsuru will try to guess the application’s name based on the git repository’s configuration. It will try to find a remote labeled tsuru, and parse its URL.

If no remote named tsuru is found, tsuru will try to use the current directory name as the application’s name.

List of available platforms

$ tsuru platform-list

Lists the available platforms. All platforms displayed in this list may be used to create new apps (see app-create).

List of available plans

$ tsuru plan-list [--human]

List available plans that can be used when creating an app.

Create an application

$ tsuru app-create <appname> <platform> [--plan/-p plan_name] [--team/-t (team owner)]

Creates a new app using the given name and platform. For tsuru, a platform is provisioner dependent. To check the available platforms, use the command tsuru platform-list and to add a platform use the command tsuru-admin platform-add.

In order to create an app, you need to be member of at least one team. All teams that you are member (see tsuru team-list) will be able to access the app.

The --platform parameter is the name of the platform to be used when creating the app. This will definer how tsuru understands and executes your app. The list of available platforms can be found running tsuru platform-list.

The --plan parameter defines the plan to be used. The plan specifies how computational resources are allocated to your application. Typically this means limits for memory and swap usage, and how much cpu share is allocated. The list of available plans can be found running tsuru plan-list.

If this parameter is not informed, tsuru will choose the plan with the default flag set to true.

The --team parameter describes which team is responsible for the created app, this is only needed if the current user belongs to more than one team, in which case this parameter will be mandatory.

Minimum # of arguments: 2

Remove an application

$ tsuru app-remove [-a/--app appname] [-y/--assume-yes]

Removes an application. If the app is bound to any service instance, all binds will be removed before the app gets deleted (see tsuru service-unbind).

You need to be a member of a team that has access to the app to be able to remove it (you are able to remove any app that you see in tsuru app-list).

List your applications

$ tsuru app-list

Lists all apps that you have access to. App access is controlled by teams. If your team has access to an app, then you have access to it.

Display information about an application

$ tsuru app-info [-a/--app appname]

Shows information about an specific app. Its state, platform, git repository, etc. You need to be a member of a team that access to the app to be able to see informations about it.

Show logs of an application

$ tsuru app-log [-a/--app appname] [-l/--lines numberOfLines] [-s/--source source] [-u/--unit unit] [-f/--follow]

Shows log entries for an application. These logs include everything the application send to stdout and stderr, alongside with logs from tsuru server (deployments, restarts, etc.)

The --lines flag is optional and by default its value is 10.

The --source flag is optional and allows filtering logs by log source (e.g. application, tsuru api).

The --unit flag is optional and allows filtering by unit. It’s useful if your application has multiple units and you want logs from a single one.

The --follow flag is optional and makes the command wait for additional log output

Stop an application

$ tsuru app-stop [-a/--app appname]

Stops an application.

Start an application

$ tsuru app-start [-a/--app appname]

Starts an application.

Restart an application

$ tsuru app-restart [-a/--app appname]

Restarts an application.

Swap the routing between two applications

$ tsuru app-swap <app1-name> <app2-name> [-f/--force]

Swaps routing between two apps. This allows zero downtime and makes rollback as simple as swapping the applications back.

Use --force if you want to swap applications with a different numbers of units or diferent platform without confirmation.

Minimum # of arguments: 2

Add new units to an application

$ tsuru unit-add <# of units> [-a/--app appname]

Adds new units (instances) to an application. You need to have access to the app to be able to add new units to it.

Minimum # of arguments: 1

Remove units from an application

$ tsuru unit-remove <# of units> [-a/--app appname]

Removes units (instances) from an application. You need to have access to the app to be able to remove units from it.

Minimum # of arguments: 1

Change an application team owner

$ tsuru app-set-team-owner <new-team-owner> [-a/--app appname]

Sets owner team for an application.

Minimum # of arguments: 1

Allow a team to access an application

$ tsuru app-grant <teamname> [-a/--app appname]

Allows a team to access an application. You need to be a member of a team that has access to the app to allow another team to access it. grants access to an app to a team.

Minimum # of arguments: 1

Revoke a team’s access to an application

$ tsuru app-revoke <teamname> [-a/--app appname]

Revokes the permission to access an application from a team. You need to have access to the application to revoke access from a team.

An application cannot be orphaned, so it will always have at least one authorized team.

Minimum # of arguments: 1

Run an arbitrary command in application’s containers

$ tsuru app-run <command> [commandarg1] [commandarg2] ... [commandargn] [-a/--app appname] [-o/--once]

Runs an arbitrary command in application’s containers. The base directory for all commands is the root of the application.

If you use the --once flag tsuru will run the command only in one unit. Otherwise, it will run the command in all units.

Minimum # of arguments: 1

Open a shell to an application’s container

$ tsuru app-shell [container-id] -a/--app <appname>

Opens a remote shell inside container, using the API server as a proxy. You can access an app container just giving app name.

Also, you can access a specific container from this app. In this case, you have to specify part of the container’s ID. You can list current container’s IDs using tsuru app-info.

Open a remote shell to the given container, or to one of the containers of the given app.


$ tsuru app-deploy [-a/--app <appname>] <file-or-dir-1> [file-or-dir-2] ... [file-or-dir-n]

Deploys set of files and/or directories to tsuru server. Some examples of calls are:

$ tsuru app-deploy .
$ tsuru app-deploy myfile.jar Procfile

Minimum # of arguments: 1

List deploys

$ tsuru app-deploy-list [-a/--app <appname>]

List information about deploys for an application.

Rollback deploy

$ tsuru app-deploy-rollback [-a/--app appname] [-y/--assume-yes] <image-name>

Deploys an existing image for an app. You can list available images with tsuru app-deploy-list.

Minimum # of arguments: 1

Public Keys

Add SSH public key

$ tsuru key-add <key-name> <path/to/key/>

Sends your public key to the git server used by tsuru. The key will be added to the current logged in user.

Minimum # of arguments: 2

Remove SSH public key

$ tsuru key-remove <key-name>

Removes your public key from the git server used by tsuru. The key will be removed from the current logged in user.

Minimum # of arguments: 1

List SSH public keys

$ tsuru key-list [-n/--no-truncate]

Lists the public keys registered in the current user account.


List available services and instances

$ tsuru service-list

Retrieves and shows a list of services the user has access. If the are instances created for any service they will also be shown.

Create a new service instance

$ tsuru service-add <servicename> <serviceinstancename> [plan] [-t/--owner-team <team>]

Creates a service instance of a service. There can later be binded to applications with tsuru service-bind.

This example shows how to add a new instance of mongodb service, named tsuru_mongodb with the plan small:

$ tsuru service-add mongodb tsuru_mongodb small -t myteam

Minimum # of arguments: 2 Maximum # of arguments: 3

Remove a service instance

$ tsuru service-remove <serviceinstancename> [--assume-yes]

Destroys a service instance. It can’t remove a service instance that is bound to an app, so before remove a service instance, make sure there is no apps bound to it (see tsuru service-info command).

Minimum # of arguments: 1

Display information about a service

$ tsuru service-info <service-name>

Displays a list of all instances of a given service (that the user has access to), and apps bound to these instances.

Minimum # of arguments: 1

Check if a service instance is up

$ tsuru service-status <service-instance-name>

Displays the status of the given service instance. For now, it checks only if the instance is “up” (receiving connections) or “down” (refusing connections).

Minimum # of arguments: 1

Check if a service instance is up

$ tsuru service-doc <service-name>

Shows the documentation of a service.

Minimum # of arguments: 1

Bind an application to a service instance

$ tsuru service-bind <service-instance-name> [-a/--app appname]

Binds an application to a previously created service instance. See tsuru service-add for more details on how to create a service instance.

When binding an application to a service instance, tsuru will add new environment variables to the application. All environment variables exported by bind will be private (not accessible via tsuru env-get).

Minimum # of arguments: 1

Unbind an application from a service instance

$ tsuru service-unbind <instancename> [-a/--app appname]

Unbinds an application from a service instance. After unbinding, the instance will not be available anymore. For example, when unbinding an application from a MySQL service, the application would lose access to the database.

Minimum # of arguments: 1

Environment variables

Applications running on tsuru should use environment variables to handle configurations. As an example, if you need to connect with a third party service like twitter’s API, your application is going to need things like an api_key.

In tsuru, the recommended way to expose these values to applications is using environment variables. To make this easy, tsuru provides commands to set and get environment variables in a running application.

Set environment variables

$ tsuru env-set <NAME=value> [NAME=value] ... [-a/--app appname]

Sets environment variables for an application.

Minimum # of arguments: 1

Show environment variables

$ tsuru env-get [-a/--app appname] [ENVIRONMENT_VARIABLE1] [ENVIRONMENT_VARIABLE2] ...

Retrieves environment variables for an application.

Unset environment variables


Unset environment variables for an application.

Minimum # of arguments: 1

Plugin management

Plugins allow extending tsuru client’s functionality. Plugins are executables existing in $HOME/.tsuru/plugins.

Installing a plugin

There are two ways to install. The first way is to manually copy your plugin to $HOME/.tsuru/plugins. The other way is to use tsuru plugin-install command.

Install a plugin

$ tsuru plugin-install <plugin-name> <plugin-url>

Downloads the plugin file. It will be copied to $HOME/.tsuru/plugins.

Minimum # of arguments: 2

List installed plugins

$ tsuru plugin-list

List installed tsuru plugins.

Remove a plugin

$ tsuru plugin-remove <plugin-name>

Removes a previously installed tsuru plugin.

Minimum # of arguments: 1

Executing a plugin

To execute a plugin just follow the pattern tsuru <plugin-name> <args>:

$ tsuru <plugin-name>

CNAME management

Add a CNAME to the app

$ tsuru cname-add <cname> [<cname> ...] [-a/--app appname]

Adds a new CNAME to the application.

It will not manage any DNS register, it’s up to the user to create the DNS register. Once the app contains a custom CNAME, it will be displayed by “app- list” and “app-info”.

Minimum # of arguments: 1

Remove a CNAME from the app

$ tsuru cname-remove <cname> [<cname> ...] [-a/--app appname]

Removes a CNAME from the application. This undoes the change that cname-add does.

After unsetting the CNAME from the app, tsuru app-list and tsuru app- info will display the internal, unfriendly address that tsuru uses.

Minimum # of arguments: 1

Auto Scale

Configure auto scale

$ tsuru autoscale-config [-a/--app appname] --max-units unitsnumber --min-units unitsnumber --increase-step unitsnumber --increase-wait-time seconds --increase-expression expression --decrease-wait-time seconds --decrease-expression expression --enabled

config app autoscale.

Enable auto scale

$ tsuru autoscale-enable [-a/--app appname]

Enables application autoscale.

Disable auto scale

$ tsuru autoscale-disable [-a/--app appname]

Disablse application autoscale.