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
acsCLI. From a console window, run the following command to install the CLI:
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.
| Name | Description |
|---|---|
appname | The 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_serverid | Show server ID in logs. |
--start_date <start_date> | Starting date for retrieving logs. |
--end_date | Ending date for retrieving logs. |
--per_page | The number of log messages per page. Default: 100 |
--more | Display the next page of log messages. |
--full_content | Show 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, --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 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).
| 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. |
--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. |
--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. |
--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 |
--unset <var> | Unsets the specified environment variable. |
--env | Lists set environment variables. |
-h, --help | Displays help information about the command. |
crt
Manages custom SSL certificates for accessing your application via HTTPS.
| 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 <cert> | Add a certificate for the app. The certificate should be a PEM file containing a signed certificate, all intermediate certificates, and a private key (pass phrase eliminated). |
--remove | Removes 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, --help | Displays 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.
| 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. |
--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. |
--check | Check the current domain setting. |
-h, --help | Displays 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.
| Name | Description |
|---|---|
appname | The 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, --help | Displays help information about the command. |
inspect
Use the inspect command to gather detailed information for published services.
| Name | Description |
|---|---|
appname | The name of the published app to gather detailed information on. |
ID | The 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, --help | Displays 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.
| Name | Description |
|---|---|
appname | Name of the app to list information for. |
--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. |
-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.
| Name | Description |
|---|---|
appname | Name of the app to log information for. |
--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. |
--show_serverid | Show 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.
| 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. |
--login_registry | Login to the private Docker registry. |
-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.
| Name | Description |
|---|---|
| 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. |
| The ID of the server to retrieve logs from. An application may be deployed to multiple servers in the cloud. |
--build_log | Displays the application build log. Does not work with the --server_id or --show_serverid options. |
--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. |
--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 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.
| Name | Description |
|---|---|
name | Name of the app to create. |
--type <type> | Create a new app of the specified type. Available options are free and image. |
--force | Force 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, --help | Show help information for this command. |
ps
Lists the service tasks for the specified app.
| Name | Description |
|---|---|
appname | The 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, --help | Show 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.
| Name | Description |
|---|---|
appname | The 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. |
| 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. |
--list_versions | List 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. |
--async | Publish 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_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.
| 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.
| Name | Description |
|---|---|
appname | The 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 --help | Show help information for this command. |
restore
Restores the specified app.
| Name | Description |
|---|---|
appkey | The key to the app to restore. |
-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.
| 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 <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, --help | Show help information for this command. |
transfer-domain
Transfer a domain name from an app to another.
| Name | Description |
|---|---|
domain_name | The 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, --help | Show 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.
| 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. |
-h, --help | Show 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.
| 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 | 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. |
--per_page <per_page> | The number of usage logs per page. Default: 100 |
--more | Display the next page of log messages. |
- | 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. |
whoami
Shows the currently logged-in user and organizations you belong to.
| Name | Description |
|---|---|
--output <value> | 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. |
acs-stack commands
crt
Upload or remove a certificate.
| Name | Description |
|---|---|
certificateFile | The name of the certificate file to add or remove. |
add | Add the specified certificate file. |
rm | Remove the specified certificate file. |
-c, --cert <cert> | Specify the certificate. |
-o, --org <orgid> | Specify the organization for the involved stack. |
-h, --help | Show help information for this command. |
deploy
Deploy a new stack.
| Name | Description |
|---|---|
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, --help | Show help information for this command. |
inspect
Inspect a service.
| Name | Description |
|---|---|
stack-name | Specify the name of the stack to inspect. |
service-name | Specify the name of the service to inspect. |
ID | Specify the ID of the service to inspect. |
-o, --org <orgid> | Specify the organization for the involved stack. |
-h, --help | Show help information for this command. |
log
Get logs for a stack service.
| Name | Description |
|---|---|
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. |
--more | Get more service logs. |
-o, --org <orgid> | Specify the organization for the involved stack. |
-h, --help | Show help information for this command. |
logcat
Get continuous logs for a stack service.
| Name | Description |
|---|---|
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, --help | Show help information for this command. |
ls
List stacks.
| Name | Description |
|---|---|
stack-name | Specify the name of the stack to list stacks for. |
-m, --mine | Show stacks only created by the user. |
-o, --org <orgid> | Specify the organization for the involved stack. |
-h, --help | Show help information for this command. |
ps
Check service tasks.
| Name | Description |
|---|---|
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. |
ID | Specify the ID of the service to check service tasks for. |
-o, --org <orgid> | Specify the organization for the involved stack. |
-h, --help | Show help information for this command. |
rm
Remove a stack.
| Name | Description |
|---|---|
stack-name | Specify the name of the stack to remove. |
-o, --org <orgid> | Specify the organization for the involved stack. |
-h, --help | Show help information for this command. |
rollback
Rollback a service.
| Name | Description |
|---|---|
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, --help | Show help information for this command. |
scale
Scale a service.
| Name | Description |
|---|---|
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, --help | Show help information for this command. |
services
Check services of a stack.
| Name | Description |
|---|---|
stack-name | Specify the name of the stack in which to check services. |
-o, --org <orgid> | Specify the organization for the involved stack. |
-h, --help | Show help information for this command. |
update
Update a service.
| Name | Description |
|---|---|
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. |
--force | Force an update even if no changes require it. |
-o, --org <orgid> | Specify the organization for the involved stack. |
-h, --help | Show help information for this command. |