API Runtime Services Command-Line Interface Reference

Introduction

API Runtime Services uses the Appcelerator Cloud Services command-line interface, called acs for short, for creating and administering applications in the API Runtime Services environment. By default, the Appcelerator CLI or Studio handles the installation of the acs CLI tool.

Setup

The Appcelerator CLI or Studio manages the installation of the acs CLI. To run acs subcommands, use the appc cloud subcommand.

To manually install the acs CLI, independent of the other tools:

Download and install Node.js from http://nodejs.org/#download, which includes the npm package manager needed to install the acs CLI.

From a console window, run the following command to install the CLI:

[sudo] npm install acs -g

Login to API Runtime Services.

acs login

Most commands require you to be logged in. If you do not run commands in the project's directory, in most commands, you need to either specify the app name as the last parameter or specify the project's location with the -d parameter.

`acs` commands

accesslog

List application's access logs within a specified period. By default, a maximum of 100 log messages will be returned at a time.

acs accesslog [options] [appname]

Name	Description
appname	The name of the app to retrieve and show access logs for. If omitted, you must run the command in the application's root directory, or specify the application's directory with '-d' option.
`--server_id` <serverid>	Id of the server which the logs from. An app may be deployed to multiple servers in the cloud.
`--show_serverid`	Show server ID in logs.
`--start_date <start_date>`	Starting date for retrieving logs.
`--end_date <end_date>`	Ending date for retrieving logs.
`--org <orgID>`	The ID of the organization the application belongs to. This parameter only is required if the target application has the same name as an application in another organization you belong to.
`--per_page <per_page>`	The number of log messages per page. Default: 100
`--more`	Display the next page of log messages.
`-h`, `--help`	Show help information for this command.

Dates are specified as YYYY-MM-DD or "YYYY-MM-DD HH:MM". Note that if the time is included, the date string must be quoted. If the specified date range contains more than specified maximum number of logs, the most recent messages will be returned.

add

Icon

This feature is deprecated as of API Runtime Services (Arrow Cloud) 1.6.

Adds a new route or service to an existing application. The name parameter specifies the new the route's name, as well as the name of the handler function.

acs add name [ -d <app_directory> ]

Name	Description
name	Name of the new route/service to add.
`-d`, `--dir` `<app_directory>`	Specifies the application to add a route to.
`-h`, `--help`	Show help information for this command.

autoshutdown

Automatically deactivate non-development containers after the specified number of seconds.

acs autoshutdown <n>

Name	Description
`<n>`	The number of seconds. This value needs to be set to greater than 3600 or set to 0. If the value is not set or is set to 0, the application will not deactivate if its type is not development. Note: Development containers will still be deactivated after 7 days of inactivity.
`-h`, `--help`	Show help information for this command.

config

The config command configures environment variables and the number of cloud servers for the application to use (auto-scaling).

                      
                            ### Environment variables
acs config [--set <key>=<value>] [--unset <key>] [--env]
                              [appname]
### Auto-scaling
acs config [--autoscaleup true|false] [--autoscaledown true|false] [--minsize N] [--maxsize N] [--maxqueuedrequests N] [--usagenotice true|false] [appname]

Name

Description

appname The name of the app to configure cloud server resources for. If omitted, the command needs to be run in the application's root directory, or specify the application's directory with the -d or --directory option.

--autoscaleup Boolean (default is false). Enables or disables automatically scaling up the number of cloud servers based on the maxqueuedrequests setting.

--autoscaledown Boolean (default is false). Enables or disables automatically scaling down the number of cloud servers based on the maxqueuedrequests setting.

--env Lists set environment variables.

--maxqueuedrequests <n> Specifies the maximum number of queued requests for autoscaling to occur. The number should be based on the response time of your application; the longer the response time is, the smaller this value should be. API Runtime Services will increase the number of containers if the queue is too high for at least one minute. The default value is 50.

--set <key>=<value>

Sets an environment variable.

To set more than one variable, comma separate the key-value pairs. For example:

                              
                                    acs config --set "extra_hosts=54.219.6.230 www.163.com;54.219.6.230 www.123.com"

To access the variable in the application, prefix the variable with the process.env namespace.

--maxsize <n> Sets the maximum number of cloud servers to use.

--minsize <n> Sets the minimum number of cloud servers to use.

--unset <key> Unsets the specified environment variable.

--usagenotice Boolean (default is true). Enables or disables app resource usage email notification.

--org orgID The ID of the organization the application belongs to. This parameter only is required if the target application has the same name as an application in another organization you belong to.

-h, --help

Displays help information about the command.

crt

Manages custom SSL certificates for accessing your application via HTTPS.

acs crt [options] [appname]

Name	Description
appname	The name of the app to associate with the SSL certificate. If omitted, the command needs to be run from the application's root directory, or specify the application's directory with the `-d` option.
`--add <PEM-file>`	Adds the SSL certificate contained by the specified PEM file.
`--remove`	Removes the SSL certificate of the associated application, if one exists.
`--orgorgID`	The ID of the organization the application belongs to. This parameter only is required if the target application has the same name as an application in another organization you belong to.

domain

Binds a domain to a published application, so that the application can be accessed using a custom domain as an alias for the application's cloud.appcelerator.com URL.

acs domain [ options ] [ appname ]

Name	Description
`appname`	The name of the app to set the domain for. If omitted, the command needs to be run in application's root directory, or specify the application's directory with the `-d` option.
`--check`	Check the current domain setting.
`--path <path_name>`	Specifies a URL path for routing. Use this parameter when setting more than one application to the same domain name. Set the domain first.
`--set <domain_name>`	Set domain binding for the application to the specified domain name. A domain record must exist for the specified domain name, pointing to the application's `cloud.appcelerator.com` URL. Do not specify the protocol, that is, do not add `http://` or `https://`, when setting this parameter. You may bind up to five domain names to the application.
`--remove [domain_name]`	Remove domain binding from the application. If the application has more than one domain, you will be prompted to select the domain to remove or you can optionally specify the domain to remove.
`--org <orgID>`	The ID of the organization the application belongs to. This parameter only is required if the target application has the same name as an application in another organization you belong to.

list

Shows a list of applications owned by the current user. By default, data is listed for all applications. You can specify an application name to only show details for that application. The information returned by this command also includes error messages, if any, related to the application's deployment and execution.

acs list [ appname | -h ]

Name	Description
`--mine`	Only list apps created by the current user.
`--org <orgID>`	Lists applications of the specified organization ID.
`--show_all`	Show all servers in the result if there are more than ten servers; otherwise, only servers whose status are not deployed will be shown.
appname	Name of the app to list information for.
`-h, --help`	Show help information for this command.

logcat

Retrieves and displays a published application's runtime logs continuously from API Runtime Services. It lets you see in real-time what's happening with an application running in the cloud. By default, runtime logs are retrieved every five seconds, and you can configure this interval with the --interval parameter. The interval cannot be smaller than five seconds.

acs logcat [ options ] [ appname ]

Name	Description
`--server_id serverid`	The ID of the server to retrieve logs from. An application may be deployed to multiple servers in the cloud.
`--show_serverid`	Show server ID in logs.
`--interval interval`	Interval for retrieving application logs, in seconds. Default: 5s.
`--build_log`	Displays the application retrieve log. Does not work with the `--server_id` or `--show_serverid` options.
`--org orgID`	The ID of the organization the application belongs to. This parameter is required if the target application has the same name as an application in another organization you belong to.
`-h`, `--help`	Show help information for this command.

Command for logging in to API Runtime Services using your AMPLIFY Appcelerator Services account credentials.

acs login [<username>] [<password>] [--host <hostname>]

Name	Description
`<username>`	Your AMPLIFY Appcelerator Services account user name. If not specified, you are prompted for the username.
`<password>`	Your AMPLIFY Appcelerator Services account password. If not specified, you are prompted for the password.
`--host`	The ACS host to log in to. If not specified, the command attempts to log in to the host specified by the `~/.acs` configuration file, or `admin.cloudapp.appcelerator.com` if not specified by the `~/.acs` file.
`-h`, `--help`	Show help information for this command.

loglist

Lists the application's log within a specific period. By default, a maximum of 100 log messages is returned at a time.

acs loglist [ options ] [ <appname> | -d <app_dir> ]

Name	Description
appname	The name of the app to retrieve and show runtime logs for. If omitted, you must run the command in the application's root directory, or specify the application's directory with `-d` option.
--server_id <serverid>	ID of the server to retrieve logs from. An application may be deployed to multiple servers in the cloud.
--show_serverid	Show server ID in logs.
--build_log	Displays the application build log. Does not work with the `--server_id` or `--show_serverid` options.
--start_date <start_date>	Starting date for retrieving logs.
--end_date <end_date>	Ending date for retrieving logs.
--per_page <per_page>	Number of log messages per page. Default: 100.
--more	Display the next page of log messages.
`--org <orgID>`	The ID of the organization the application belongs to. This parameter only is required if the target application has the same name as an application in another organization you belong to.
-h, --help	Show help information for this command.

Dates are specified as YYYY-MM-DD or "YYYY-MM-DD HH:MM". Note that if the time is included, the date string must be quoted. If the specified date range contains more than specified maximum number of logs, the most recent messages will be returned.

logout

Logout from API Runtime Services.

acs logout

new

Starting with API Runtime Services (Arrow Cloud) 1.6.0, acs new creates a sample Node.js, app and acs new --image creates a sample app with Dockerfile.

publish

Publishes and runs an application on the API Runtime Services. This command also lists all currently published versions and the currently deployed version.

Note that if an application is not listening on port 80, use acs config --set PORT=customport to make publish work. Also, note that publishing an application now supports publishing Docker images directly.

                      
                            acs publish [-d | --dir <application-directory> ] [ --list_versions
                              ] [ --set_active_version <version>] [ --delete_oldest ] [--git <options|config_file>]
                              [ --force ] [-h | --help] [npm_username] [npm_password]

Name

Description

--d, --dir <APP_DIRECTORY> Specifies the directory of the application to publish. When omitted, the command must be run from the application directory.

--force Required when publishing a version of an application that's already been published.

--git <OPTIONS|CONFIG_FILE>

Requires CLI Version 1.0.24 or greater. Publish a Github repo. Pass in the following comma-delimited options or in a configuration file in JSON format:

Key	Required	Description
repo	true	URL of the Git repo.
branch	false	Branch to use.
access_token	false	Personal access token generated by Github.
username	false	Github username if the repo is private.
password	false	Github password if the repo is private.

--list_versions List all published versions of the application, and the version deployed currently if any.

npm_username
npm_password NPM repository credentials if you are using dependencies from a private NPM repository.

--org <ORG_ID> The ID of the organization the application belongs to. You only need to this parameter if you have published an application with the same name to multiple organizations.

--set_active_version <VERSION> Set the currently deployed and active version of the application to version.

--delete_oldest Delete the oldest version if published versions reached the max number of versions (10).

-h, --help Show help information for this command.

For a newly installed on-premise cluster, if the Domain Name System (DNS) is not configured for the Mobile Backend Services endpoint, use acs config --set "extra_hosts=<ip> api.<domain> <appname>" before or after publish for your app to reference to the Mobile Backend Services endpoint that is not in the database. This applies to all endpoints that don't exist in the DNS yet and extra_hosts can take a list of entries. such as

acs config --set "extra_hosts=54.219.6.230 www.163.com;54.219.6.230 www.123.com" <appname>

For appc publish, you can include it in appc.json:

"environment": {"extra_hosts":"54.212.208.81 api.cloudapp-1.appctest.com"},

remove

Removes an application. If the application has been published, the command unpublishes the application first, then removes it. The local application directory is not deleted by default. Use the --force option to delete it.

acs remove [ options ] [ <appname> ]

Name	Description
<appname>	The name of the app to remove. If omitted, you must run the command in the application's root directory, or specify the application's directory with the `-d` option.
`--force`	Remove local application directory. The application must be specified using -d option which specifies the target application directory or the command is running in application's root directory.
`--org <orgID>`	The ID of the organization the application belongs to. This parameter is required if the target application has the same name as an application in another organization you belong to.
`-h`, `--help`	Show help information for this command.

restart

Released with Appcelerator CLI 6.0.0, this command allows you to restart an API Runtime Services application without having to use acs publish --force

Note: This command will restart all servers associated with your app.

acs restart [options] [appname]

Name	Description
--org <orgid>	organization ID of the app if there are multiple apps with the same name in different organizations.
-h --help	output usage information

run

Icon

This feature is deprecated as of API Runtime Services (Arrow Cloud) 1.6.

Start an API Runtime Services application locally for development and testing purposes.

acs run [ options ]

Name	Description
`-p`, `--port <port_number>`	Start the application on a specific port. If omitted, port '8080' is used. This option only takes effect for applications using the MVC framework.
`--random`	Start application with a random port. This option only takes effect for applications using the API Runtime Services MVC Framework.
`-h,` `--help`	Show help information for this command.

server

The server command configures the server container size of the application. If your application is already published after changing the container size, you will need to republish the application.

acs server [<appname>] --set <SERVER_SIZE>] [--org <ORG_ID>]

Name	Description
`<appname>`	The name of the app to configure cloud server resources for. If omitted, the command needs to be run in the application's root directory, or specify the application's directory with the `-d` or `--directory` option.
`--set <SERVER_SIZE>`	Sets the server size. Values can be one of the following: `Dev`, `Small`, `Medium`, `Large` or `XLarge`. See API Builder Project for specifics on these sizes.
`--restart <SERVER_ID>`	Restarts the server. You may want to run the restart command if the application is using too much memory or CPU cycles on the server. To get the server ID the application is running on, use the `acs list` command.
`--org ORG_ID`	The ID of the organization the application belongs to. This parameter only is required if the target application has the same name as an application in another organization you belong to.
`-h`, `--help`	Displays help information of the command.

unpublish

By default, unpublishes the currently deployed and active application, shutting the application down and deleting it from the API Runtime Services cloud. You can also unpublish a specific version with the --ver option, regardless of whether it is deployed or not. The local application directory is not removed after an unpublish operation, so you can republish the application again with the publish command.

acs unpublish [ <appname> |--dir <app_dir>] [--ver <version>]

Name	Description
`<appname>`	Name of the app to be unpublished. If omitted, the command needs to be run in application's root directory, or the application's directory must be specified with the `-d` or `--dir` option.
`--ver <version>`	Un-publishes the version of the application specified by version. If not specified, the currently deployed version is unpublished.
`--org <orgID>`	The ID of the organization the application belongs to. This parameter is required if the target application has the same name as an application in another organization you belong to.

usage

Check server system resource usage within a specific period. The server in cloud logs CPU/memory usage periodically. By default, a maximum of 100 log entries will be returned at a time.

acs usage [options] [appname]

Name	Description
appname	The name of the app to retrieve and show system resource usage for. If omitted, the command needs to be run in application's root directory, or specify the application's directory with the `-d` option.
`--server_id <serverid>`	The id of the server which the logs are from. An app may be deployed to multiple servers in the cloud.
`--show_serverid`	Show server ID in logs.
`--start_date` <start_date>	Starting date for retrieving usage logs.
`--end_date` <end_date>	Ending date for retrieving usage logs.
`--page_number <` page_number>	Page of usage log output to display, where 1 is the most recent.
`--per_page <` per_page>	Number of usage logs per page. Default: 100
`--more`	Display the next page of log messages.
`--org <orgID>`	The ID of the organization the application belongs to. This parameter is required if the target application has the same name as an application in another organization you belong to.
`-h`, --help	Show help information about the command.

whoami

Shows the currently logged-in user and organizations you belong to.

acs whoami

Name	Description
`--output <format>`	Sets the output format. Set to either report for human-readable format or json for JSON output. Defaults to report.
`-h`, `--help`	Show help information for this command.