App Services CLI
Overview
The Atlas App Services Command Line Interface (appservices
) allows you
to programmatically manage your Applications.
With the App Services CLI, you can create or update Apps from a local directory as well as export existing applications to a local directory.
Installation
App Services CLI is available on npm
. To install the CLI on your system,
ensure that you have Node.js
installed and then run the following command in your shell:
npm install -g atlas-app-services-cli
Authentication
To use the App Services CLI, you must authenticate. To authenticate, you must generate an API Key.
Generate an API Key
Navigate to MongoDB Cloud Access Manager
The MongoDB Cloud Access Manager allows you to manage access to your project for users, teams, and API Keys. Use the Project Access Manager by clicking the Project Access tab on the access manager dropdown on your screen's top left-hand side.
Create an API Key
Project Users can log in with a Project API Key. Create a project API Key by clicking the grey Create API Key button on the right-hand side of the Project Access Manager.
Clicking this button navigates you to the "Create API Key" screen. Set a description for your key.
For write access, the CLI requires an API key with "Project Owner" permissions. For read-only access, you can use "Project Read Only". Use the Project Permissions dropdown to select the appropriate permissions for your use case.
Copy the public key to use later in order to log in. Click next to continue configuring your key details.
Configure Your API Access List
Copy your Private Key to a safe location for later use. For security, the Private Key will not be visible again after initialization. Another security feature is the API Access List. Creating an API Access List entry ensures that API calls originate from permitted IPs.
The IP Address of the user who will be using the API Key is required to use the key. Click the Add Access List Entry button. Type in the IP Address or click the Use Current IP Address buttton and click save. Finally, click the done button on your screen's lower right-hand to finish setting up your API key.
Authenticate with an API Key
The .mdb
Directory
When you use the App Services CLI to push or pull configuration files, the CLI
stores information about the App you're working with in the .mdb
directory of your application config. This allows the CLI to remember a
specific deployment that your configuration files are associated with
across multiple commands.
This directory is machine generated and you typically should not
manually modify it. If you delete the .mdb
directory, the CLI will
no longer be able to associate your configuration files with a specific
deployment. The CLI creates a new .mdb
directory when you run a
command that targets a specific deployment.
The CLI stores identifiers and configuration metadata in the
.mdb/meta.json
file, which has the following format:
{ "config_version": 20230101, "app_id": "42249d526d97af5a287c1eae", "group_id": "4b2cf422930196872221a2d4", "client_app_id": "myapp-abcde" }
Field | Description |
---|---|
config_version number | The configuration file format version that all configuration
files in the directory conform to. This is used to ensure that
the CLI can read the configuration files. |
app_id string | The App's internal ObjectId value. |
group_id string | The Atlas Project ID that the App is associated with. |
client_app_id string | The human-readable Client App ID. |
CLI Profiles
The CLI stores information about its users in a profile. This lets you run commands in a given context. For example, when you log in with an Atlas Admin API Key, the CLI stores the API Key and the current session access token. Then it reuses that token for subsequent commands until it expires.
You can set up multiple named profiles and choose a profile to use for
any given CLI command. If you don't specify one, the CLI uses the
default profile, which is a profile named default
.
To specify a profile, add the --profile
argument on any command. For
example, to log in with a new profile named my-profile
,
run the following:
appservices login --profile my-profile
Once logged in, you can run other commands with the same profile:
appservices pull --remote=myapp-abcde --profile my-profile
You can list all profiles on your system with a CLI command:
appservices profiles list
Found 2 profile(s) Profile API Key ---------- ----------------------------------------------- my-profile rjxerfwi (********-****-****-****-f00b471ec015) default xkwwtlmj (********-****-****-****-f03b321dae23)
The CLI stores profiles on your computer in individual configuration files named after the profile. The location of the profile definitions depends on your system:
Operating System | Profile Directory |
---|---|
Unix / Linux | $XDG_CONFIG_HOME/<profile>.yaml or $HOME/.config/<profile>.yaml |
macOS | $HOME/Library/Application\ Support/appservices-cli/<profile>.yaml |
Windows | %AppData%/<profile>.yaml |
Options
Name | Type | Required | Description |
---|---|---|---|
--profile | string | false | Specify your profile (Default value: "default") [Learn more] |
--telemetry | string | false | Enable/Disable CLI usage tracking for your current profile (Default value: "on"; Allowed values: "on", "off") |
-o, --output-target | string | false | Write CLI output to the specified filepath |
-f, --output-format | string | false | Set the CLI output format (Default value: <blank>; Allowed values: <blank>, "json") |
--disable-colors | false | Disable all CLI output styling (e.g. colors, font styles, etc.) | |
-y, --yes | false | Automatically proceed through CLI commands by agreeing to any required user prompts | |
-h, --help | false | help for appservices |
Related Commands
appservices accessList - Manage the allowed IP addresses and CIDR blocks of your app (aliases: accesslist, access-list)
appservices apps - Manage the App Service Apps associated with the current user (alias: app)
appservices deploy - Manage automatic deployments of your app
appservices function - Interact with the Functions of your app (alias: functions)
appservices login - Log the CLI into App Services using a MongoDB Cloud API Key
appservices logout - Log the CLI out of App Services
appservices logs - Interact with the Logs of your app (alias: log)
appservices pull - Pulls the latest version of your app into your local directory
appservices push - Pushes and deploys changes from your local directory to your app
appservices schema - Manage the Schemas of your app (alias: schemas)
appservices secrets - Manage the Secrets of your app (alias: secret)
appservices users - Manage the Users of your app (alias: user)
appservices whoami - Display information about the current user