Skip to end of metadata
Go to start of metadata

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:

  1. Download and install Node.js from http://nodejs.org/#download, which includes the npm package manager needed to install the acs CLI.
  2. From a console window, run the following command to install the CLI: 

  3. Login to API Runtime Services. 

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.

NameDescription
appnameThe name of the application 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 the -d option.
--server_id <serverid>The ID of the server which the logs are from. An application may be deployed to multiple servers in the cloud.
--show_serveridShow server ID in logs.
--start_date <start_date> Starting date for retrieving logs.
--end_date <end_date> Ending date for retrieving logs.
--per_page <per_page>
The number of log messages per page. Default: 100
--moreDisplay the next page of log messages.
--full_contentShow full access 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.
-h--helpShow 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 the specified maximum number of logs, the most recent messages will be returned.

config

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

NameDescription
appnameThe 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.
--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.
--autoscaleupBoolean (default is false). Enables or disables automatically scaling up the number of cloud servers based on the maxqueuedrequests setting.
--autoscaledownBoolean (default is false). Enables or disables automatically scaling down the number of cloud servers based on the maxqueuedrequests setting.
--maxqueuedrequests <var>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.
--maxsize <n>Sets the maximum number of cloud servers to use.
--minsize <n>Sets the minimum number of cloud servers to use.
--maxconn <n>Set the maximum per-server number of concurrent connections for the app.
--maxconnws <n>Set the maximum per-server number of concurrent web socket connections for the app.
--autoshutdown <n>Automatically deactivate non-development container after n seconds (value needs to be greater than 3600 or set to 0). If the value is not set or set to 0, the app will not deactivate if its type isn't development. Regardless, development containers will still be deactivated after 7 days of inactivity.
--set <var>

Sets an environment variable.

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

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

--unset <var>Unsets the specified environment variable.
--envLists set environment variables.
-h--help

Displays help information about the command.

crt

Manages custom SSL certificates for accessing your application via HTTPS.

NameDescription
appnameThe 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 <cert>Add a certificate for the app. The certificate should be a PEM file containing a signed certificate, intermediate certificates, and a private key (passphrase eliminated).
--removeRemoves the SSL certificate of the associated application, if one exists.
--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--helpDisplays help information about the command.

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.

NameDescription
appnameThe 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.
--set <domain>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]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.
--path <path>Specifies a URL path for routing. Use this parameter when setting more than one application to the same domain name. Set the domain first.
--checkCheck the current domain setting.
-h--helpDisplays help information about the command.

download

Download the app source file with specified app name and version. If no app name is provided, specify the app directory with either dir or -d. The currently deployed app version will be downloaded if no app version option provided.

NameDescription
appnameThe name of the app to download. If omitted, the command needs to be run in application's root directory, or specify the application's directory with the -d option.
--ver <version>The app version to download. If not specified, the currently deployed version will be downloaded.
--path <local_path>The existing local path to which to store the app source file.
--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--helpDisplays help information about the command.

inspect

Use the inspect command to gather detailed information for published services.

NameDescription
appnameThe name of the published app to gather detailed information on.
IDThe ID of the published app to gather detailed information on.
-o, --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, --helpDisplays help information about the command.

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.

NameDescription
appnameName of the app to list information for.
--mineOnly list apps created by the current user.
--org <orgID>
Lists applications of the specified organization ID.
--show_allShow all servers in the result if there are more than ten servers; otherwise, only servers whose status are not deployed will be shown.
-h, --helpShow 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.

NameDescription
appnameName of the app to log information for.
--interval <interval>Interval for retrieving application logs, in seconds. Default: 5s.
--build_logDisplays the application retrieve log. Does not work with the --server_id or --show_serverid options.
--show_serveridShow server ID in logs.
--server_id <server_id>The ID of the server to retrieve logs from. An application may be deployed to multiple servers in the cloud.
--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.

login

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

NameDescription
usernameYour AMPLIFY Appcelerator Services account username. If not specified, you are prompted for the username.
passwordYour AMPLIFY Appcelerator Services account password. If not specified, you are prompted for the password.
--hostThe 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.
--login_registryLogin to the private Docker registry.
-h--helpShow 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. 

NameDescription

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 the -d option.

--server_id <serverid>

The ID of the server to retrieve logs from. An application may be deployed to multiple servers in the cloud.
--build_logDisplays the application build log. Does not work with the --server_id or --show_serverid options.
--show_serveridShow server ID in logs.
--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.
--moreDisplay 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, --helpShow 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 the specified maximum number of logs, the most recent messages will be returned.

logout

Logout from API Runtime Services.

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.

NameDescription
nameName of the app to create.
--type <type>Create a new app of the specified type. Available options are free and image.
--forceForce to use existing local app directory (add existing project to the cloud).
--org <orgid>Create an app for the specified organization.
--env <envid>Create an app for the specified environment.
-h, --helpShow help information for this command.

ps

Lists the service tasks for the specified app.

NameDescription
appnameThe name of the app to list service tasks for.
--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, --helpShow help information for this command.

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.

NameDescription
appnameThe name of the app to publish. If omitted, you must run the command in the application's root directory, or specify the application's directory with the -d option.
npm_username
npm_password
NPM repository credentials if you are using dependencies from a private NPM repository.

--d, --dir <app_directory>

Specifies the directory of the application to publish. When omitted, the command must be run from the application directory.
--forceRequired when publishing a version of an application that's already been published.
--list_versionsList all published versions of the application, and the version deployed currently if any.
--set_active_version <version>Set the currently deployed and active version of the application to version.
--org <orgid>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.
--asyncPublish an app without waiting for fully deployed onto the cloud.
--image <name[:tag]>The name of the docker image will use the latesttag if a tag is not specified. Only the image type needs to specify this option.
--app_version <version>The version of the app to be published. Only the image type needs to specify this option.
--delete_oldestDelete the oldest version if published versions reached the max number of versions (10).
-h--helpShow 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.

NameDescription
appnameThe 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.
--forceRemove 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--helpShow 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.

NameDescription
appnameThe name of the app to restart. If omitted, you must run the command in the application's root directory, or specify the application's directory with the -d option.
--org <orgid>

organization ID of the app if there are multiple apps with the same name in different organizations.

-h --helpShow help information for this command.

restore

Restores the specified app.

NameDescription
appkey
The key to the app to restore.
-h, --helpShow 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.

NameDescription
appnameThe 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 <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.
--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--helpShow help information for this command.

transfer-domain

Transfer a domain name from an app to another.

NameDescription
domain_nameThe name of the domain to transfer from one app to another app.
--from <source app>The app that currently owns the domain name.
--to <target app>The app to receive the domain name.
-h--helpShow help information for this 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.

NameDescription
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.
-h--helpShow help information for this command.

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.

NameDescription
appnameThe 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_serveridShow server ID in logs.
--start_date <start_date>Starting date for retrieving usage logs.
--end_date <end_date>Ending date for retrieving usage logs.
--per_page <per_page>The number of usage logs per page. Default: 100
--moreDisplay 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, --helpShow help information for this command.

whoami

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

NameDescription
--output <value>Sets the output format. Set to either report for human-readable format or json for JSON output. Defaults to report.
-h--helpShow help information for this command.

acs-stack commands

crt

Upload or remove a certificate.

NameDescription
certificateFile

The name of the certificate file to add or remove.

addAdd the specified certificate file.
rmRemove the specified certificate file.
-c, --cert <cert>Specify the certificate.
-o, --org <orgid>Specify the organization for the involved stack.
-h--helpShow help information for this command.

deploy

Deploy a new stack.

NameDescription
stack-name
Name of the stack to deploy.
-c, --compose <compose-file>Specify the compose file for the stack.
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.

inspect

Inspect a service.

NameDescription
stack-name
Specify the name of the stack to inspect.
service-name
Specify the name of the service to inspect.
IDSpecify the ID of the service to inspect.
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.

log

Get logs for a stack service.

NameDescription
stack-name
Specify the name of the stack to get logs from.
service-name
Specify the name of the service to get logs from.
--server <server-id>Specify service ID for checking service logs.
--start <start-time>Specify the start time for checking service logs.
--end <end-time>Specify the end time for checking service logs.
--moreGet more service logs.
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.

logcat

Get continuous logs for a stack service.

NameDescription
stack-name
Specify the name of the stack to get continuous logs from.
service-name
Specify the name of the service to get continuous logs from.
--server <server-id>Specify the service ID for checking service logs.
--interval <interval>Specify a longer interval in seconds for periodically checking service logs. Min: 5
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.

ls

 List stacks.

NameDescription
stack-nameSpecify the name of the stack to list stacks for.
-m, --mineShow stacks only created by the user.
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.

ps

Check service tasks.

NameDescription
stack-name
Specify the name of the stack to check service tasks for.
service-name
Specify the name of the service to check service tasks for.
IDSpecify the ID of the service to check service tasks for.
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.

rm

Remove a stack.

NameDescription
stack-name
Specify the name of the stack to remove.
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.

rollback

Rollback a service.

NameDescription
stack-name
Specify the name of the stack in which to rollback a service.
service-name
Specify the name of the service to rollback.
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.

scale

Scale a service.

NameDescription
stack-name
Specify the name of the stack in which to scale a service.
service-name
Specify the name of the service to scale.
relicas
Specify the name of the relics to rollback.
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.

services

Check services of a stack.

NameDescription
stack-name
Specify the name of the stack in which to check services.
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.

update

Update a service.

NameDescription
stack-name
Specify the name of the stack in which to update a service.
service-name
Specify the name of the service to update.
--envadd <name>=<val>Add an environment variable.
--envrm <name>Remove an environment variable.
--image <image-tag>Specify a service image tag.
--forceForce an update even if no changes require it.
-o, --org <orgid>Specify the organization for the involved stack.
-h, --helpShow help information for this command.