diff --git a/config/redirects b/config/redirects index 8a669ae6a..91184e8c5 100644 --- a/config/redirects +++ b/config/redirects @@ -264,7 +264,44 @@ raw: docs/atlas/app-servicesAtlas%20App%20Services -> ${base}/ raw: ${prefix}/manage-apps/secure -> ${base}/security/ ## (DOCSP-30776): Make "Tiered Device Sync" page public and change its name -raw: ${prefix}/sync/app-builder/tiered-device-sync/index -> ${base}/edge-server/ - ## (DOCSP-32967): Make "Edge Server" page a section +raw: ${prefix}/sync/app-builder/tiered-device-sync/index -> ${base}/edge-server/ raw: ${prefix}/sync/app-builder/edge-server/ -> ${base}/edge-server/ + +# realm-cli -> appservices-cli +raw: ${prefix}/cli/realm-cli-accessList-create -> ${base}/realm-cli/realm-cli-accessList-create/ +raw: ${prefix}/cli/realm-cli-accessList-delete -> ${base}/realm-cli/realm-cli-accessList-delete/ +raw: ${prefix}/cli/realm-cli-accessList-list -> ${base}/realm-cli/realm-cli-accessList-list/ +raw: ${prefix}/cli/realm-cli-accessList-update -> ${base}/realm-cli/realm-cli-accessList-update/ +raw: ${prefix}/cli/realm-cli-accessList -> ${base}/realm-cli/realm-cli-accessList/ +raw: ${prefix}/cli/realm-cli-apps-create -> ${base}/realm-cli/realm-cli-apps-create/ +raw: ${prefix}/cli/realm-cli-apps-delete -> ${base}/realm-cli/realm-cli-apps-delete/ +raw: ${prefix}/cli/realm-cli-apps-describe -> ${base}/realm-cli/realm-cli-apps-describe/ +raw: ${prefix}/cli/realm-cli-apps-diff -> ${base}/realm-cli/realm-cli-apps-diff/ +raw: ${prefix}/cli/realm-cli-apps-init -> ${base}/realm-cli/realm-cli-apps-init/ +raw: ${prefix}/cli/realm-cli-apps-list -> ${base}/realm-cli/realm-cli-apps-list/ +raw: ${prefix}/cli/realm-cli-apps -> ${base}/realm-cli/realm-cli-apps/ +raw: ${prefix}/cli/realm-cli-function-run -> ${base}/realm-cli/realm-cli-function-run/ +raw: ${prefix}/cli/realm-cli-function -> ${base}/realm-cli/realm-cli-function/ +raw: ${prefix}/cli/realm-cli-login -> ${base}/realm-cli/realm-cli-login/ +raw: ${prefix}/cli/realm-cli-logout -> ${base}/realm-cli/realm-cli-logout/ +raw: ${prefix}/cli/realm-cli-logs-list -> ${base}/realm-cli/realm-cli-logs-list/ +raw: ${prefix}/cli/realm-cli-logs -> ${base}/realm-cli/realm-cli-logs/ +raw: ${prefix}/cli/realm-cli-pull -> ${base}/realm-cli/realm-cli-pull/ +raw: ${prefix}/cli/realm-cli-push -> ${base}/realm-cli/realm-cli-push/ +raw: ${prefix}/cli/realm-cli-reference-v1 -> ${base}/realm-cli/realm-cli-reference-v1/ +raw: ${prefix}/cli/realm-cli-schema-datamodels -> ${base}/realm-cli/realm-cli-schema-datamodels/ +raw: ${prefix}/cli/realm-cli-schema -> ${base}/realm-cli/realm-cli-schema/ +raw: ${prefix}/cli/realm-cli-secrets-create -> ${base}/realm-cli/realm-cli-secrets-create/ +raw: ${prefix}/cli/realm-cli-secrets-delete -> ${base}/realm-cli/realm-cli-secrets-delete/ +raw: ${prefix}/cli/realm-cli-secrets-list -> ${base}/realm-cli/realm-cli-secrets-list/ +raw: ${prefix}/cli/realm-cli-secrets-update -> ${base}/realm-cli/realm-cli-secrets-update/ +raw: ${prefix}/cli/realm-cli-secrets -> ${base}/realm-cli/realm-cli-secrets/ +raw: ${prefix}/cli/realm-cli-users-create -> ${base}/realm-cli/realm-cli-users-create/ +raw: ${prefix}/cli/realm-cli-users-delete -> ${base}/realm-cli/realm-cli-users-delete/ +raw: ${prefix}/cli/realm-cli-users-disable -> ${base}/realm-cli/realm-cli-users-disable/ +raw: ${prefix}/cli/realm-cli-users-enable -> ${base}/realm-cli/realm-cli-users-enable/ +raw: ${prefix}/cli/realm-cli-users-list -> ${base}/realm-cli/realm-cli-users-list/ +raw: ${prefix}/cli/realm-cli-users-revoke -> ${base}/realm-cli/realm-cli-users-revoke/ +raw: ${prefix}/cli/realm-cli-users -> ${base}/realm-cli/realm-cli-users/ +raw: ${prefix}/cli/realm-cli-whoami -> ${base}/realm-cli/realm-cli-whoami/ diff --git a/snooty.toml b/snooty.toml index 6eb857e34..17a5c6be0 100644 --- a/snooty.toml +++ b/snooty.toml @@ -34,15 +34,25 @@ toc_landing_pages = [ "/schemas", "/data-api", "/tutorials", - # CLI + # App Services CLI "/cli", - "/cli/realm-cli-accessList", - "/cli/realm-cli-apps", - "/cli/realm-cli-function", - "/cli/realm-cli-logs", - "/cli/realm-cli-schema", - "/cli/realm-cli-secrets", - "/cli/realm-cli-users", + "/cli/appservices-accessList", + "/cli/appservices-apps", + "/cli/appservices-function", + "/cli/appservices-logs", + "/cli/appservices-schema", + "/cli/appservices-secrets", + "/cli/appservices-users", + # [Deprecated] Realm CLI + "/realm-cli", + "/realm-cli/v2", + "/realm-cli/v2/realm-cli-accessList", + "/realm-cli/v2/realm-cli-apps", + "/realm-cli/v2/realm-cli-function", + "/realm-cli/v2/realm-cli-logs", + "/realm-cli/v2/realm-cli-schema", + "/realm-cli/v2/realm-cli-secrets", + "/realm-cli/v2/realm-cli-users", # Reference "/reference/config", # Other @@ -58,8 +68,9 @@ adf = "Atlas Data Federation" adf-datasource = "Federated data source" adf-instance = "Federated database instance" base-url = "https://www.mongodb.com/docs/atlas/app-services" -cli = "Realm CLI" -cli-bin = ":binary:`realm-cli`" # binary -- DO NOT USE IN LINKS! Will break them. +cli = "App Services CLI" +cli-bin = "appservices" +cli-ref = ":ref:`App Services CLI `" deployment-history-size = "25" log-retention-time = "10 days" max-concurrent-requests = "10,000" diff --git a/source/activity/forward-logs.txt b/source/activity/forward-logs.txt index 90c23963c..0a775a232 100644 --- a/source/activity/forward-logs.txt +++ b/source/activity/forward-logs.txt @@ -323,7 +323,7 @@ log forwarder by name. .. code-block:: sh - realm-cli push + {+cli-bin+} push Restart a Suspended Log Forwarder --------------------------------- diff --git a/source/activity/view-logs.txt b/source/activity/view-logs.txt index fb4ccca8a..0832c77b0 100644 --- a/source/activity/view-logs.txt +++ b/source/activity/view-logs.txt @@ -58,12 +58,12 @@ with the App Services CLI. View Recent Logs ~~~~~~~~~~~~~~~~ -To return the 100 most recent log entries for your application, run ``realm-cli +To return the 100 most recent log entries for your application, run ``{+cli-bin+} logs list``. .. code-block:: shell - realm-cli logs list + {+cli-bin+} logs list Tail Logs in Real Time ~~~~~~~~~~~~~~~~~~~~~~ @@ -73,7 +73,7 @@ as they come in. .. code-block:: shell - realm-cli logs list --tail + {+cli-bin+} logs list --tail View Error Logs ~~~~~~~~~~~~~~~ @@ -83,7 +83,7 @@ the flag, the command returns both error logs and regular logs. .. code-block:: shell - realm-cli logs list --errors + {+cli-bin+} logs list --errors Filter Logs by Type ~~~~~~~~~~~~~~~~~~~ @@ -104,7 +104,7 @@ The following types are valid: .. code-block:: shell - realm-cli logs list --type=function --type=trigger + {+cli-bin+} logs list --type=function --type=trigger .. _cli-view-logs-for-date-range: @@ -117,7 +117,7 @@ together. .. code-block:: shell - realm-cli logs list --start="2021-01-01T00:00:00.000+0000" --end="2021-02-01T00:00:00.000+0000" + {+cli-bin+} logs list --start="2021-01-01T00:00:00.000+0000" --end="2021-02-01T00:00:00.000+0000" App Services API ---------------- diff --git a/source/apps/cicd.txt b/source/apps/cicd.txt index 3ced44e7f..716abd545 100644 --- a/source/apps/cicd.txt +++ b/source/apps/cicd.txt @@ -138,15 +138,13 @@ the Development stage or use your production App ID in the Production stage. `. Set Up {+cli+} -~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~ -:ref:`{+cli+} ` is the easiest way to programmatically create, -configure, and manage App Services Apps. You should :ref:`install ` -and use the latest version in your deployment scripts. +The {+cli+} is the easiest way to programmatically +create, configure, and manage Atlas Apps. You should install and +use the latest version in your deployment scripts. -.. code-block:: bash - - npm install -g mongodb-realm-cli +.. include:: /includes/install-appservices-cli.rst You'll also need a MongoDB Atlas public/private API key pair to authenticate and use the CLI. For more information and a walkthrough of how to get an API key, @@ -157,7 +155,7 @@ To log in, save your API keys in a new named profile configuration and then log in with that profile: .. code-block:: yaml - :caption: ~/.config/realm-cli/.yaml + :caption: ~/.config/{+cli-bin+}/.yaml : public_api_key: "" @@ -168,7 +166,7 @@ in with that profile: .. code-block:: bash - realm-cli login --profile="" + {+cli-bin+} login --profile="" .. tip:: @@ -194,7 +192,7 @@ To use a new app for your development or staging branch: .. code-block:: bash cd path/to/realmApp - realm-cli push -y --project="" # e.g. --project="609ea544934fe445460219a2" + {+cli-bin+} push -y --project="" # e.g. --project="609ea544934fe445460219a2" 2. **Save the App ID** @@ -205,7 +203,7 @@ To use a new app for your development or staging branch: .. code-block:: bash # Save to an environment variable - output=$(realm-cli app describe) + output=$({+cli-bin+} app describe) app_id=$(echo $output | sed 's/^.*client_app_id": "\([^"]*\).*/\1/') export REALM_APP_ID=app_id # Save to a file @@ -224,7 +222,7 @@ To update an existing app, specify its App ID in the ``--remote`` flag: .. code-block:: bash - realm-cli push --remote=$REALM_APP_ID -y + {+cli-bin+} push --remote=$REALM_APP_ID -y Run Tests Against the App ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/apps/copy.txt b/source/apps/copy.txt index 91b10ed4b..a6b830c28 100644 --- a/source/apps/copy.txt +++ b/source/apps/copy.txt @@ -43,7 +43,7 @@ Before You Begin - .. include:: /includes/prereqs/atlas-admin-api-key.rst - - .. include:: /includes/prereqs/app-services-cli.rst + - .. include:: /includes/prereqs/appservices-cli.rst .. tab:: :tabid: github @@ -80,7 +80,7 @@ Procedure .. code-block:: bash # Create the new App - realm-cli app create \ + {+cli-bin+} app create \ --name "myapp-copy" \ --deployment-model "LOCAL" \ --location "US-OR" @@ -100,7 +100,7 @@ Procedure .. code-block:: bash # Pull the config files for an existing App - realm-cli pull --remote="myapp-abcde" + {+cli-bin+} pull --remote="myapp-abcde" .. include:: /apps/copy-app-copy-config-files.rst @@ -117,7 +117,7 @@ Procedure # Navigate back to the new App cd myapp-copy # Push the copied configuration files to App Services - realm-cli push + {+cli-bin+} push .. tab:: :tabid: github @@ -157,7 +157,7 @@ Procedure cd myapp-copy # Create the new App. The create command saves the new # App's configiration file directory in the current directory - realm-cli app create \ + {+cli-bin+} app create \ --name "myapp-copy" \ --deployment-model "LOCAL" \ --location "US-OR" diff --git a/source/apps/create.txt b/source/apps/create.txt index cd7b09dda..fe3e7fa53 100644 --- a/source/apps/create.txt +++ b/source/apps/create.txt @@ -44,7 +44,7 @@ Before You Begin - .. include:: /includes/prereqs/atlas-admin-api-key.rst - - .. include:: /includes/prereqs/app-services-cli.rst + - .. include:: /includes/prereqs/appservices-cli.rst .. tab:: :tabid: api @@ -145,7 +145,7 @@ Procedure .. code-block:: shell - realm-cli apps create + {+cli-bin+} apps create The command also supports additional flags that you can optionally include to customize your app. The following table lists common flags you might use: @@ -183,7 +183,7 @@ Procedure .. seealso:: For more details and additional flags, see the - :ref:`CLI documentation for the create command `. + :ref:`CLI documentation for the create command `. .. tab:: :tabid: api diff --git a/source/apps/delete.txt b/source/apps/delete.txt index a05ccfcaf..1b00c317c 100644 --- a/source/apps/delete.txt +++ b/source/apps/delete.txt @@ -33,7 +33,7 @@ Before You Begin - .. include:: /includes/prereqs/atlas-admin-api-key.rst - - .. include:: /includes/prereqs/app-services-cli.rst + - .. include:: /includes/prereqs/appservices-cli.rst - .. include:: /includes/prereqs/app-id.rst @@ -94,7 +94,7 @@ Procedure .. code-block:: shell - realm-cli apps delete + {+cli-bin+} apps delete If you have more than one App, you will be prompted to select one or more apps that you would like to delete from a list of all your Apps. @@ -104,12 +104,12 @@ Procedure .. code-block:: shell - realm-cli apps delete --app + {+cli-bin+} apps delete --app .. seealso:: For more details and additional flags, see the - CLI documentation for the :ref:`app delete ` command. + CLI documentation for the :ref:`app delete ` command. .. tab:: :tabid: api diff --git a/source/apps/environment.txt b/source/apps/environment.txt index 503d57226..672d2c3f4 100644 --- a/source/apps/environment.txt +++ b/source/apps/environment.txt @@ -100,7 +100,7 @@ Before You Begin - .. include:: /includes/prereqs/atlas-admin-api-key.rst - - .. include:: /includes/prereqs/app-services-cli.rst + - .. include:: /includes/prereqs/appservices-cli.rst - .. include:: /includes/prereqs/app-id.rst @@ -233,7 +233,7 @@ Procedure .. code-block:: bash - realm-cli push --remote="" + {+cli-bin+} push --remote="" .. tab:: :tabid: api diff --git a/source/apps/export.txt b/source/apps/export.txt index 6bde9c502..033e56bea 100644 --- a/source/apps/export.txt +++ b/source/apps/export.txt @@ -48,7 +48,7 @@ Before You Begin - .. include:: /includes/prereqs/atlas-admin-api-key.rst - - .. include:: /includes/prereqs/app-services-cli.rst + - .. include:: /includes/prereqs/appservices-cli.rst - .. include:: /includes/prereqs/app-id.rst @@ -113,7 +113,7 @@ Procedure .. code-block:: shell - realm-cli pull --remote= + {+cli-bin+} pull --remote= By default the command pulls files into the current working directory. You can configure the command to create a new @@ -122,7 +122,7 @@ Procedure .. code-block:: shell - realm-cli pull --remote= --local= + {+cli-bin+} pull --remote= --local= .. tip:: @@ -131,7 +131,7 @@ Procedure pull the configuration files. The command also supports :ref:`additional flags - ` that you can optionally include to + ` that you can optionally include to customize your app. The following table lists common flags you might use: diff --git a/source/apps/metadata.txt b/source/apps/metadata.txt index 91fe2c8d7..ea6f582e3 100644 --- a/source/apps/metadata.txt +++ b/source/apps/metadata.txt @@ -109,8 +109,8 @@ or App Services CLI to find it programmatically. .. .. tab:: :tabid: cli -.. To find an App ID, run :ref:`realm-cli apps list - ` and find the App you're interested in the +.. To find an App ID, run :ref:`{+cli-bin+} apps list + ` and find the App you're interested in the list returned by the command. .. Each entry in the list contains two App ID values you may want: @@ -127,7 +127,7 @@ or App Services CLI to find it programmatically. .. .. input:: :language: bash -.. realm-cli apps list +.. {+cli-bin+} apps list .. .. output:: :language: text diff --git a/source/apps/update.txt b/source/apps/update.txt index e818c5251..66a678d3f 100644 --- a/source/apps/update.txt +++ b/source/apps/update.txt @@ -62,7 +62,7 @@ Before You Begin - .. include:: /includes/prereqs/atlas-admin-api-key.rst - - .. include:: /includes/prereqs/app-services-cli.rst + - .. include:: /includes/prereqs/appservices-cli.rst .. tab:: :tabid: api @@ -164,7 +164,7 @@ Procedure .. code-block:: bash - realm-cli push --remote="" + {+cli-bin+} push --remote="" .. tab:: :tabid: api @@ -271,7 +271,7 @@ to deploy immediately when you save in the UI. The {+cli+} and :ref:`GitHub Deployment ` both automatically create and deploy drafts for you. When you run the CLI -:ref:`push ` command or ``git push`` to your deployment +:ref:`push ` command or ``git push`` to your deployment branch, the CLI or GitHub app creates a diff of your local configuration files against the currently deployed configuration. Then it creates and deploys a draft based on the diff. diff --git a/source/authentication/anonymous.txt b/source/authentication/anonymous.txt index c31a69b56..beb2f6595 100644 --- a/source/authentication/anonymous.txt +++ b/source/authentication/anonymous.txt @@ -98,7 +98,7 @@ Configuration :tabid: cli To enable and configure the Anonymous authentication provider with - :ref:`realm-cli `, define a :ref:`configuration + the {+cli-ref+}, define a :ref:`configuration object ` for it in ``/auth/providers.json``. Anonymous provider configurations have the following form: diff --git a/source/authentication/api-key.txt b/source/authentication/api-key.txt index 2044fa5d9..2f2021600 100644 --- a/source/authentication/api-key.txt +++ b/source/authentication/api-key.txt @@ -51,7 +51,7 @@ The API Key authentication provider does not have any configuration options. :tabid: cli To enable and configure the API Key authentication provider with - :ref:`realm-cli `, define a :ref:`configuration + ``{+cli-ref+}``, define a :ref:`configuration object ` for it in ``/auth/providers.json``. API Key provider configurations have the following form: @@ -138,20 +138,20 @@ You must enable the API key provider before you can create an API key. .. tab:: :tabid: cli - - To create a new server API key, call ``realm-cli users create`` and + + To create a new server API key, call ``{+cli-bin+} users create`` and specify ``--type=api-key``. The CLI will prompt you for your App ID as well as a name for the new API key. .. code-block:: bash - - realm-cli users create --type=api-key - - You can also specify the arguments in the command: - + + {+cli-bin+} users create --type=api-key + + You can also specify the arguments when you call the program: + .. code-block:: bash - - realm-cli users create --type=api-key \ + + {+cli-bin+} users create --type=api-key \ --app= \ --name= diff --git a/source/authentication/apple.txt b/source/authentication/apple.txt index 4d343038d..792b45321 100644 --- a/source/authentication/apple.txt +++ b/source/authentication/apple.txt @@ -233,7 +233,7 @@ To use Sign in with Apple exclusively with either a web or a mobile application, :tabid: cli To enable and configure the Apple authentication provider with - :ref:`realm-cli `, define a :ref:`configuration + {+cli-bin+}, define a :ref:`configuration object ` for it in ``/auth/providers.json``. Apple provider configurations have the following form: @@ -291,7 +291,7 @@ To use Sign in with Apple exclusively with either a web or a mobile application, .. code-block:: shell - realm-cli push + {+cli-bin+} push To deploy a draft application with automatic :ref:`GitHub deployment `: @@ -509,7 +509,7 @@ To use Sign in with Apple exclusively with either a web or a mobile application, :tabid: cli To enable and configure the Apple authentication provider with - :ref:`realm-cli `, define a :ref:`configuration + ``{+cli-bin+}``, define a :ref:`configuration object ` for it in ``/auth/providers.json``. Apple provider configurations have the following form: @@ -581,7 +581,7 @@ To use Sign in with Apple exclusively with either a web or a mobile application, .. code-block:: shell - realm-cli push + {+cli-bin+} push To deploy a draft application with automatic :ref:`GitHub deployment `: diff --git a/source/authentication/custom-function.txt b/source/authentication/custom-function.txt index e2b02658d..ffdcb27dc 100644 --- a/source/authentication/custom-function.txt +++ b/source/authentication/custom-function.txt @@ -259,7 +259,7 @@ deployment method. .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" .. tip:: @@ -312,7 +312,7 @@ deployment method. .. code-block:: bash - realm-cli push --remote="" + {+cli-bin+} push --remote="" Configure Custom User Data diff --git a/source/authentication/custom-jwt.txt b/source/authentication/custom-jwt.txt index 9f4c7132c..9aa017c9c 100644 --- a/source/authentication/custom-jwt.txt +++ b/source/authentication/custom-jwt.txt @@ -93,9 +93,9 @@ preferred method below. .. tab:: :tabid: cli - To enable and configure the Custom JWT authentication provider - with the CLI, define a configuration object for the provider in - ``/auth/providers.json``. + To enable and configure the Custom JWT authentication provider with + {+cli-ref+}, define a :ref:`configuration + object ` for it in ``/auth/providers.json``. A :ref:`Custom JWT provider configuration ` has the following form: diff --git a/source/authentication/email-password.txt b/source/authentication/email-password.txt index 70b8aae4a..52380297b 100644 --- a/source/authentication/email-password.txt +++ b/source/authentication/email-password.txt @@ -53,7 +53,7 @@ Configuration :tabid: cli To enable and configure the Email/Password authentication provider with - :ref:`realm-cli `, define a :ref:`configuration + the {+cli-ref+}, define a :ref:`configuration object ` for it in ``/auth/providers.json``. Email/Password provider configurations have the following form: @@ -141,9 +141,9 @@ App Services APIs: .. tab:: :tabid: cli - To view pending users with the Realm CLI, use the - `List Users `__ - endpoint and include the ``--pending`` option. + To view pending users with the Realm CLI, use the + :ref:`appservices users list ` + command and include the ``--pending`` option. .. tab:: :tabid: api diff --git a/source/authentication/facebook.txt b/source/authentication/facebook.txt index e95665829..ea0898ea3 100644 --- a/source/authentication/facebook.txt +++ b/source/authentication/facebook.txt @@ -52,7 +52,7 @@ Configuration :tabid: cli To enable and configure the Facebook authentication provider with - :ref:`realm-cli `, define a :ref:`configuration + the {+cli-ref+}, define a :ref:`configuration object ` for it in ``/auth/providers.json``. Facebook provider configurations have the following form: diff --git a/source/authentication/firebase-jwt.txt b/source/authentication/firebase-jwt.txt index e80b2b906..73f51c0e5 100644 --- a/source/authentication/firebase-jwt.txt +++ b/source/authentication/firebase-jwt.txt @@ -23,8 +23,8 @@ You will need the following to use Firebase Authentication: authentication. To learn how to create a new App Services App, see :ref:`Create an App `. -- If you're using the command line interface, you need :ref:`realm-cli - ` to be installed and authenticated on your local system. +- If you're using the command line interface, you need {+cli-ref+} to be + installed and authenticated on your local system. - If you're using the Admin API, you need a MongoDB Atlas Admin API :atlas:`public/private key pair @@ -122,7 +122,7 @@ Choose your preferred method below. .. code-block:: bash - realm-cli pull --remote "myapp-abcde" + {+cli-bin+} pull --remote "myapp-abcde" cd myapp Add a new Custom JWT authentication provider to your App's @@ -143,7 +143,7 @@ Choose your preferred method below. .. code-block:: bash - realm-cli push + {+cli-bin+} push .. tab:: :tabid: api diff --git a/source/authentication/google.txt b/source/authentication/google.txt index 53bfef0a9..81be688c3 100644 --- a/source/authentication/google.txt +++ b/source/authentication/google.txt @@ -205,7 +205,7 @@ Configure in App Services :tabid: cli To enable and configure the Google authentication provider with - :ref:`realm-cli `, define a :ref:`configuration + the {+cli-ref+}, define a :ref:`configuration object ` for it in ``/auth/providers.json``. Google provider configurations have the following form: diff --git a/source/authentication/okta-jwt.txt b/source/authentication/okta-jwt.txt index 14fc411cc..ae3a576de 100644 --- a/source/authentication/okta-jwt.txt +++ b/source/authentication/okta-jwt.txt @@ -23,8 +23,7 @@ You will need the following to use Okta: authentication. To learn how to create a new App Services App, see :ref:`Create an App `. -- If you're using the command line interface, you need :ref:`realm-cli - ` to be installed and authenticated on your local system. +- If you're using the command line interface, you need {+cli-ref+} to be installed and authenticated on your local system. - If you're using the Admin API, you need a MongoDB Atlas Admin API :atlas:`public/private key pair @@ -111,7 +110,7 @@ Choose your preferred method below. .. code-block:: bash - realm-cli pull --remote "myapp-abcde" + {+cli-bin+} pull --remote "myapp-abcde" cd myapp Add a new Custom JWT authentication provider to your App's @@ -137,7 +136,7 @@ Choose your preferred method below. .. code-block:: bash - realm-cli push + {+cli-bin+} push .. tab:: :tabid: api diff --git a/source/cli.txt b/source/cli.txt index 18df6c0ad..406b86235 100644 --- a/source/cli.txt +++ b/source/cli.txt @@ -1,137 +1,22 @@ -.. _realm-cli: -.. _realm-cli-quickstart: +.. _appservices-cli: -========= +================ {+cli+} -========= +================ .. default-domain:: mongodb .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 1 :class: singlecol -Overview --------- - -.. program:: realm-cli -.. binary:: realm-cli - -The Atlas App Services Command Line Interface ({+cli-bin+}) -allows you to programmatically manage your App Services Apps. -With {+cli-bin+}, you can create or update -Apps from a local directory as well as export -existing applications to a local directory. - -.. important:: Check your CLI version - - This page is a quickstart for version 2 of {+cli-bin+}. If you need - documentation for version 1 of {+cli-bin+}, see: :ref:`{+cli+} v1 `. - To check your CLI version, use: ``realm-cli --version``. - To upgrade your global install to the latest version, use: ``npm upgrade -g mongodb-realm-cli``. - -.. _install-realm-cli: - -Installation ------------- - -.. include:: /includes/install-realm-cli-v2.rst - -.. _cli-auth-with-api-token: - -Authentication --------------- - -To use the {+cli+}, you must authenticate. To authenticate, you must generate an -API Key. - -Generate an API Key -~~~~~~~~~~~~~~~~~~~ - -.. procedure:: - - .. step:: Navigate to MongoDB Cloud Access Manager - - The :mms-docs:`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 - :guilabel:`Project Access` tab on the :guilabel:`access manager - dropdown` on your screen's top left-hand side. - - .. figure:: /images/click-access-manager.png - :alt: Click Access Manager - :lightbox: - - - .. step:: Create an API Key - - Project Users can log in using the {+cli+} tool with a Project API - Key. Create a project API Key by clicking the grey :guilabel:`Create - API Key` button on the right-hand side of the Project Access Manager. - - .. figure:: /images/access-manager-create-api-key-button.png - :alt: Click Access Manager - :lightbox: - - 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 - :guilabel:`Project Permissions` dropdown to select the appropriate permissions - for your use case. - - Click :guilabel:`next` to continue configuring your key details. - - .. figure:: /images/configure-api-key.png - :alt: Click Access Manager - :lightbox: - - - .. step:: Configure Your API Access List - - Copy your Public and Private keys 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 :guilabel:`Add Access List Entry` button. - Type in the IP Address or click the :guilabel:`Use Current IP Address` - button and click save. Finally, click the done button on your screen's - lower right-hand to finish setting up your API key. - - .. figure:: /images/add-access-list-entry.png - :alt: Click Access Manager - :lightbox: - -Authenticate with an API Key -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. procedure:: - - .. step:: Authenticate a CLI User - - Using your newly created public and private key, log in by running the - command below. - - .. code-block:: shell - - realm-cli login --api-key="" --private-api-key="" - - You should see the following result: - - .. code-block:: shell - - you have successfully logged in as +.. include:: /includes/app-services-cli-overview.rst Options ------- -Use "realm-cli [command] --help" for information on a specific command - .. list-table:: :header-rows: 1 :widths: 20 10 10 60 @@ -142,62 +27,61 @@ Use "realm-cli [command] --help" for information on a specific command - Description * - --profile - string - - no - - Specify your profile (Default value: "default") (default "default") + - false + - Specify your profile (Default value: "default") * - --telemetry - string - - no + - false - Enable/Disable CLI usage tracking for your current profile (Default value: "on"; Allowed values: "on", "off") * - -o, --output-target - string - - no + - false - Write CLI output to the specified filepath * - -f, --output-format - string - - no + - false - Set the CLI output format (Default value: ; Allowed values: , "json") * - --disable-colors - - - no + - false - Disable all CLI output styling (e.g. colors, font styles, etc.) * - -y, --yes - - - no + - false - Automatically proceed through CLI commands by agreeing to any required user prompts * - -h, --help - - false - - help for realm-cli - -Commands --------- - -* :ref:`realm-cli-accessList` - Manage allowed IP addresses and CIDR blocks -* :ref:`realm-cli-apps` - Manage the App Services Apps associated with the current user (alias: app) -* :ref:`realm-cli-function` - Interact with the Functions of your App (alias: functions) -* :ref:`realm-cli-login` - Log the CLI into App Services using a MongoDB Cloud API key -* :ref:`realm-cli-logout` - Log the CLI out of App Services -* :ref:`realm-cli-logs` - Interact with the Logs of your App (alias: log) -* :ref:`realm-cli-pull` - Exports the latest version of your App into your local directory (alias: export) -* :ref:`realm-cli-push` - Imports and deploys changes from your local directory to your App (alias: import) -* :ref:`realm-cli-schema` - Manage the Schemas of your App (alias: schemas) -* :ref:`realm-cli-secrets` - Manage the Secrets of your App (alias: secret) -* :ref:`realm-cli-users` - Manage the Users of your App (alias: user) -* :ref:`realm-cli-whoami` - Display information about the current user + - help for appservices + +Related Commands +---------------- + +* :ref:`appservices-accessList` - Manage the allowed IP addresses and CIDR blocks of your app (aliases: accesslist, access-list) +* :ref:`appservices-apps` - Manage the App Service Apps associated with the current user (alias: app) +* :ref:`appservices-function` - Interact with the Functions of your app (alias: functions) +* :ref:`appservices-login` - Log the CLI into App Services using a MongoDB Cloud API Key +* :ref:`appservices-logout` - Log the CLI out of App Services +* :ref:`appservices-logs` - Interact with the Logs of your app (alias: log) +* :ref:`appservices-pull` - Exports the latest version of your app into your local directory (alias: export) +* :ref:`appservices-push` - Imports and deploys changes from your local directory to your app (alias: import) +* :ref:`appservices-schema` - Manage the Schemas of your app (alias: schemas) +* :ref:`appservices-secrets` - Manage the Secrets of your app (alias: secret) +* :ref:`appservices-users` - Manage the Users of your app (alias: user) +* :ref:`appservices-whoami` - Display information about the current user .. toctree:: :titlesonly: - :hidden: - accessList - apps - function - login - logout - logs - pull - push - schema - secrets - users - whoami + accessList + apps + function + login + logout + logs + pull + push + schema + secrets + users + whoami diff --git a/source/cli/appservices-accessList-create.txt b/source/cli/appservices-accessList-create.txt new file mode 100644 index 000000000..d22333d0c --- /dev/null +++ b/source/cli/appservices-accessList-create.txt @@ -0,0 +1,104 @@ +.. _appservices-accessList-create: + +============================= +appservices accessList create +============================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Create an IP address or CIDR block in the Access List for your app + +You will be prompted to input an IP address or CIDR block if none is provided in +the initial command. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices accessList create [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to create an entry in its Access List + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - --ip + - string + - false + - Specify the IP address or CIDR block that you would like to add + * - --comment + - string + - false + - Add a comment to the IP address or CIDR block (Note: This action is optional) + * - --use-current + - + - false + - Add your current IP address to your Access List + * - --allow-all + - + - false + - Allows all IP addresses to access your app (Note: “0.0.0.0/0” will be added as an entry) + * - -h, --help + - + - false + - help for create + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-accessList-delete.txt b/source/cli/appservices-accessList-delete.txt new file mode 100644 index 000000000..5f9f8a195 --- /dev/null +++ b/source/cli/appservices-accessList-delete.txt @@ -0,0 +1,93 @@ +.. _appservices-accessList-delete: + +============================= +appservices accessList delete +============================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Delete an IP address or CIDR block from the Access List of your app + +Removes an existing entry from the Access List of your app. You will be +prompted to select an IP address or CIDR block if none are provided in the +initial command. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices accessList delete [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to remove entries from its Access List + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - --ip + - strings + - false + - Specify the IP address(es) or CIDR block(s) to delete + * - -h, --help + - + - false + - help for delete + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-accessList-list.txt b/source/cli/appservices-accessList-list.txt new file mode 100644 index 000000000..aa4c2f46e --- /dev/null +++ b/source/cli/appservices-accessList-list.txt @@ -0,0 +1,88 @@ +.. _appservices-accessList-list: + +=========================== +appservices accessList list +=========================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +List the allowed entries in the Access List of your app (alias: ls) + +This will display the IP addresses and/or CIDR blocks in the Access List of +your app + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices accessList list [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to list its allowed IP addresses and/or CIDR blocks + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -h, --help + - + - false + - help for list + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-accessList-update.txt b/source/cli/appservices-accessList-update.txt new file mode 100644 index 000000000..d0c919cea --- /dev/null +++ b/source/cli/appservices-accessList-update.txt @@ -0,0 +1,101 @@ +.. _appservices-accessList-update: + +============================= +appservices accessList update +============================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Modify an IP address or CIDR block in the Access List of your app + +Changes an existing entry from the Access List of your app. You will be +prompted to select an IP address or CIDR block to update if neither is +specified. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices accessList update [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to modify an entry in its Access List + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - --ip + - string + - false + - Specify the existing IP address or CIDR block that you would like to modify + * - --new-ip + - string + - false + - Specify the new IP address or CIDR block that will replace the existing entry + * - --comment + - string + - false + - Add or edit a comment to the IP address or CIDR block that is being modified + * - -h, --help + - + - false + - help for update + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-accessList.txt b/source/cli/appservices-accessList.txt new file mode 100644 index 000000000..8d0836f02 --- /dev/null +++ b/source/cli/appservices-accessList.txt @@ -0,0 +1,84 @@ +.. _appservices-accessList: + +====================== +appservices accessList +====================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Manage the allowed IP addresses and CIDR blocks of your app (aliases: accesslist, access-list) + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -h, --help + - + - false + - help for accessList + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 + +Related Commands +---------------- + +* :ref:`appservices-accessList-create` - Create an IP address or CIDR block in the Access List for your app +* :ref:`appservices-accessList-delete` - Delete an IP address or CIDR block from the Access List of your app +* :ref:`appservices-accessList-list` - List the allowed entries in the Access List of your app (alias: ls) +* :ref:`appservices-accessList-update` - Modify an IP address or CIDR block in the Access List of your app + + +.. toctree:: + :titlesonly: + + create + delete + list + update diff --git a/source/cli/appservices-apps-create.txt b/source/cli/appservices-apps-create.txt new file mode 100644 index 000000000..97134c516 --- /dev/null +++ b/source/cli/appservices-apps-create.txt @@ -0,0 +1,146 @@ +.. _appservices-apps-create: + +======================= +appservices apps create +======================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Create a new app (or a template app) from your current working directory and deploy it to the App Services server + +Creates a new app by saving your configuration files in a local directory and +deploying the new app to the App Services server. This command will create a new +directory for your project. + +You can specify a "--remote" flag to create an app from an existing app; +if you do not specify a "--remote" flag, the CLI will create a default app. + +NOTE: To create an app without deploying it, use "app init". + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices apps create [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --remote + - string + - false + - Specify the name or ID of a remote app to clone + * - --local + - string + - false + - Specify the local filepath of an app to be created + * - -n, --name + - string + - false + - Name your new app + * - --provider-region + - string + - false + - Select the app's provider region [Learn more: https://www.mongodb.com/docs/atlas/app-services/manage-apps/deploy/deployment-models-and-regions/#cloud-deployment-regions] + * - -d, --deployment-model + - string + - false + - Select the app's deployment model (Default value: ; Allowed values: GLOBAL, LOCAL) [Learn more: https://www.mongodb.com/docs/atlas/app-services/manage-apps/deploy/deployment-models-and-regions/#deployment-models] + * - -e, --environment + - string + - false + - Select the app's environment (Default value: ; Allowed values: development, testing, qa, production) [Learn more: https://www.mongodb.com/docs/atlas/app-services/manage-apps/configure/environments/] + * - --cluster + - strings + - false + - Link Atlas cluster(s) to your app (Note: Only one cluster can be linked during app creation if creating a template app) + * - --cluster-service-name + - strings + - false + - Specify the app's Service name to reference your Atlas cluster (Note: Service names will be overwritten when creating a template app) + * - --serverless-instance + - strings + - false + - Link Atlas Serverless instance(s) to your app (Note: Serverless instances cannot be used to create template apps) + * - --serverless-instance-service-name + - strings + - false + - Specify the app's Service name to reference your Atlas Serverless instance + * - --federated-database + - strings + - false + - Link Atlas Federated Database instance(s) to your app (Note: Federated Database instances cannot be used to create template apps) + * - --federated-database-service-name + - strings + - false + - Specify the app's Service name to reference your Atlas Federated Database instance + * - --template + - string + - false + - Create your app from an available template [Learn more: https://www.mongodb.com/docs/atlas/app-services/reference/template-apps/#template-apps-available] + * - -x, --dry-run + - + - false + - Run without writing any changes to the local filepath or pushing any changes to the App Services server + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -h, --help + - + - false + - help for create + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-apps-delete.txt b/source/cli/appservices-apps-delete.txt new file mode 100644 index 000000000..663aea89b --- /dev/null +++ b/source/cli/appservices-apps-delete.txt @@ -0,0 +1,89 @@ +.. _appservices-apps-delete: + +======================= +appservices apps delete +======================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Delete an app + +If you have more than one app, you will be prompted to select one or multiple +app(s) that you would like to delete from a list of all your apps. The list +includes apps from all projects associated with your user profile. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices apps delete [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - strings + - false + - Specify the name(s) or ID(s) of apps to delete + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -h, --help + - + - false + - help for delete + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-apps-describe.txt b/source/cli/appservices-apps-describe.txt new file mode 100644 index 000000000..40212db08 --- /dev/null +++ b/source/cli/appservices-apps-describe.txt @@ -0,0 +1,89 @@ +.. _appservices-apps-describe: + +========================= +appservices apps describe +========================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Displays information about your app + +View all of the aspects of your app to see what is configured and enabled (e.g. +services, functions, etc.). If you have more than one app, you will be prompted +to select an app to view. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices apps describe [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to describe + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -h, --help + - + - false + - help for describe + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-apps-diff.txt b/source/cli/appservices-apps-diff.txt new file mode 100644 index 000000000..c51e6a672 --- /dev/null +++ b/source/cli/appservices-apps-diff.txt @@ -0,0 +1,105 @@ +.. _appservices-apps-diff: + +===================== +appservices apps diff +===================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Show differences between your local directory and your app + +Displays file-by-file differences between your local directory and the latest +version of your app. If you have more than one app, you will be prompted to +select an app to view. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices apps diff [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --local + - string + - false + - Specify the local filepath of an app to diff + * - --remote + - string + - false + - Specify the name or ID of an app to diff + * - --include-node-modules + - + - false + - Include app dependencies in the diff from a node_modules archive (Note: The allowed formats are as a directory or compressed into a .zip, .tar, .tar.gz, or .tgz file) + * - --include-package-json + - + - false + - Include app dependencies in the diff from a package.json file + * - -s, --include-hosting + - + - false + - Include app hosting files in the diff + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -h, --help + - + - false + - help for diff + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-apps-init.txt b/source/cli/appservices-apps-init.txt new file mode 100644 index 000000000..7b62c40ad --- /dev/null +++ b/source/cli/appservices-apps-init.txt @@ -0,0 +1,110 @@ +.. _appservices-apps-init: + +===================== +appservices apps init +===================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Initialize an App Services App in your current working directory (alias: initialize) + +Initializes a new App Services App by saving your configuration files in your +current working directory. + +You can specify a "--remote" flag to initialize an App Services App from an +existing app; if you do not specify a "--remote" flag, the CLI will initialize a +default App Services App. + +NOTE: To create a new App Services App and have it deployed, use "app create". + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices apps init [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --remote + - string + - false + - Specify the name or ID of a remote app to clone + * - -n, --name + - string + - false + - Name your new app + * - --provider-region + - string + - false + - Select the app's provider region [Learn more: https://www.mongodb.com/docs/atlas/app-services/manage-apps/deploy/deployment-models-and-regions/#cloud-deployment-regions] + * - -d, --deployment-model + - string + - false + - Select the app's deployment model (Default value: ; Allowed values: GLOBAL, LOCAL) [Learn more: https://www.mongodb.com/docs/atlas/app-services/manage-apps/deploy/deployment-models-and-regions/#deployment-models] + * - -e, --environment + - string + - false + - Select the app's environment (Default value: ; Allowed values: development, testing, qa, production) [Learn more: https://www.mongodb.com/docs/atlas/app-services/manage-apps/configure/environments/] + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -h, --help + - + - false + - help for init + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-apps-list.txt b/source/cli/appservices-apps-list.txt new file mode 100644 index 000000000..a30bb9597 --- /dev/null +++ b/source/cli/appservices-apps-list.txt @@ -0,0 +1,87 @@ +.. _appservices-apps-list: + +===================== +appservices apps list +===================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +List the apps you have access to (alias: ls) + +Lists and filters your apps. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices apps list [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Filter the list of apps by name + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -h, --help + - + - false + - help for list + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-apps.txt b/source/cli/appservices-apps.txt new file mode 100644 index 000000000..aedd03766 --- /dev/null +++ b/source/cli/appservices-apps.txt @@ -0,0 +1,88 @@ +.. _appservices-apps: + +================ +appservices apps +================ + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Manage the App Service Apps associated with the current user (alias: app) + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -h, --help + - + - false + - help for apps + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 + +Related Commands +---------------- + +* :ref:`appservices-apps-create` - Create a new app (or a template app) from your current working directory and deploy it to the App Services server +* :ref:`appservices-apps-delete` - Delete an app +* :ref:`appservices-apps-describe` - Displays information about your app +* :ref:`appservices-apps-diff` - Show differences between your local directory and your app +* :ref:`appservices-apps-init` - Initialize an App Services App in your current working directory (alias: initialize) +* :ref:`appservices-apps-list` - List the apps you have access to (alias: ls) + + +.. toctree:: + :titlesonly: + + create + delete + describe + diff + init + list diff --git a/source/cli/appservices-function-run.txt b/source/cli/appservices-function-run.txt new file mode 100644 index 000000000..253597054 --- /dev/null +++ b/source/cli/appservices-function-run.txt @@ -0,0 +1,104 @@ +.. _appservices-function-run: + +======================== +appservices function run +======================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Run a Function from your app + +Functions allow you to define and execute server-side logic for your app. Once +you select and run a Function for your app, the following will be displayed: + +- A list of logs, if present +- The function result as a document +- A list of error logs, if present + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices function run [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to run its function + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - --name + - string + - false + - Specify the name of the function to run + * - --args + - stringArray + - false + - Specify the args to pass to your function [Learn more: https://www.mongodb.com/docs/atlas/app-services/functions/#call-from-app-services-cli] + * - --user + - string + - false + - Specify which user to run the function as (Note: Using will run as the System user) (Default value: ; Allowed values: , ) + * - -h, --help + - + - false + - help for run + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-function.txt b/source/cli/appservices-function.txt new file mode 100644 index 000000000..5bfeaca43 --- /dev/null +++ b/source/cli/appservices-function.txt @@ -0,0 +1,78 @@ +.. _appservices-function: + +==================== +appservices function +==================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Interact with the Functions of your app (alias: functions) + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -h, --help + - + - false + - help for function + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 + +Related Commands +---------------- + +* :ref:`appservices-function-run` - Run a Function from your app + + +.. toctree:: + :titlesonly: + + run diff --git a/source/cli/appservices-login.txt b/source/cli/appservices-login.txt new file mode 100644 index 000000000..ecbea1a88 --- /dev/null +++ b/source/cli/appservices-login.txt @@ -0,0 +1,94 @@ +.. _appservices-login: + +================= +appservices login +================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Log the CLI into App Services using a MongoDB Cloud API Key + +Begins an authenticated session with App Services. To get a MongoDB Cloud API +Key, open your app in the App Services UI. Navigate to "Deployment" in the left +navigation menu, and select the "Export App" tab. From there, create a +programmatic API Key to authenticate your appservices session. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices login [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --api-key + - string + - false + - Specify the public portion of your Atlas programmatic API Key + * - --private-api-key + - string + - false + - Specify the private portion of your Atlas programmatic API Key + * - --browser + - + - false + - Direct browser to project access page to create a new API Key for logging into a project (Note: Can not be used in combination with login credentials) + * - -h, --help + - + - false + - help for login + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-logout.txt b/source/cli/appservices-logout.txt new file mode 100644 index 000000000..82ff96d90 --- /dev/null +++ b/source/cli/appservices-logout.txt @@ -0,0 +1,80 @@ +.. _appservices-logout: + +================== +appservices logout +================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Log the CLI out of App Services + +Ends the authenticated session and deletes cached auth tokens. To +re-authenticate, you must call Login with your Atlas programmatic API Key. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices logout [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -h, --help + - + - false + - help for logout + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-logs-list.txt b/source/cli/appservices-logs-list.txt new file mode 100644 index 000000000..68ac1f5ca --- /dev/null +++ b/source/cli/appservices-logs-list.txt @@ -0,0 +1,109 @@ +.. _appservices-logs-list: + +===================== +appservices logs list +===================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Lists the Logs in your app (alias: ls) + +Displays a list of your app’s Logs sorted by recentness, with most recent Logs +appearing towards the bottom. You can specify a "--tail" flag to monitor your +Logs and follow any newly created Logs in real-time. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices logs list [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to list its logs + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - --type + - Set + - false + - Specify the type(s) of logs to list (Default value: ; Allowed values: , "auth", "function", "push", "service", "trigger", "graphql", "sync", "schema") This value defaults to []. + * - --errors + - + - false + - View your app's error logs + * - --start + - Date + - false + - Specify when to begin listing logs [Learn more: https://www.mongodb.com/docs/atlas/app-services/logs/cli/#view-logs-for-a-date-range] + * - --end + - Date + - false + - Specify when to finish listing logs [Learn more: https://www.mongodb.com/docs/atlas/app-services/logs/cli/#view-logs-for-a-date-range] + * - --tail + - + - false + - View your app's logs in real-time (Note: "--start" and "--end" flags do not apply here) + * - -h, --help + - + - false + - help for list + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-logs.txt b/source/cli/appservices-logs.txt new file mode 100644 index 000000000..e96e7de2b --- /dev/null +++ b/source/cli/appservices-logs.txt @@ -0,0 +1,78 @@ +.. _appservices-logs: + +================ +appservices logs +================ + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Interact with the Logs of your app (alias: log) + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -h, --help + - + - false + - help for logs + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 + +Related Commands +---------------- + +* :ref:`appservices-logs-list` - Lists the Logs in your app (alias: ls) + + +.. toctree:: + :titlesonly: + + list diff --git a/source/cli/appservices-pull.txt b/source/cli/appservices-pull.txt new file mode 100644 index 000000000..3b2ffaf9d --- /dev/null +++ b/source/cli/appservices-pull.txt @@ -0,0 +1,113 @@ +.. _appservices-pull: + +================ +appservices pull +================ + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Exports the latest version of your app into your local directory (alias: export) + +Pulls changes from your remote app into your local directory. If applicable, +Hosting Files and/or Dependencies associated with your app will be exported as +well. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices pull [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --local + - string + - false + - Specify a local filepath to export an app to + * - --remote + - string + - false + - Specify the name or ID of a remote app to export + * - --include-node-modules + - + - false + - Export and include app dependencies from a node_modules archive (Note: The allowed formats are as a directory or compressed into a .zip, .tar, .tar.gz, or .tgz file) + * - --include-package-json + - + - false + - Export and include app dependencies from a package.json file + * - -s, --include-hosting + - + - false + - Export and include app hosting files + * - -x, --dry-run + - + - false + - Run without writing any changes to the local filepath + * - -t, --template + - strings + - false + - Specify the frontend Template ID(s) to export. (Note: Specified templates must be compatible with the remote app) [Learn more: https://www.mongodb.com/docs/atlas/app-services/reference/template-apps/#template-apps-available] + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -h, --help + - + - false + - help for pull + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-push.txt b/source/cli/appservices-push.txt new file mode 100644 index 000000000..0c41658d2 --- /dev/null +++ b/source/cli/appservices-push.txt @@ -0,0 +1,115 @@ +.. _appservices-push: + +================ +appservices push +================ + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Imports and deploys changes from your local directory to your app (alias: import) + +Updates a remote App Services App with your local directory. First, input an +app that you would like changes pushed to. This input can be either the +application Client App ID of an existing app you would like to update, or the +Name of a new app you would like to create. Changes pushed are automatically +deployed. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices push [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --local + - string + - false + - Specify the local filepath of an app to be imported + * - --remote + - string + - false + - Specify the name or ID of a remote app to edit + * - --include-node-modules + - + - false + - Import and include app dependencies from a node_modules archive (Note: The allowed formats are as a directory or compressed into a .zip, .tar, .tar.gz, or .tgz file) + * - --include-package-json + - + - false + - Import and include app dependencies from a package.json file + * - -s, --include-hosting + - + - false + - Import and include app hosting files + * - -c, --reset-cdn-cache + - + - false + - Reset the hosting CDN cache of an app + * - -x, --dry-run + - + - false + - Run without pushing any changes to the App Services server + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -h, --help + - + - false + - help for push + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-schema-datamodels.txt b/source/cli/appservices-schema-datamodels.txt new file mode 100644 index 000000000..91fc77d5e --- /dev/null +++ b/source/cli/appservices-schema-datamodels.txt @@ -0,0 +1,113 @@ +.. _appservices-schema-datamodels: + +============================= +appservices schema datamodels +============================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Generate data models based on your Schema (alias: datamodel) + +Translates your Schema’s objects into App Services data models. The data models +define your data as native objects, which can be easily integrated into your own +repo to use with Device Sync. + +NOTE: You must have a valid JSON Schema before using this command. + +With this command, you can: + - Specify the language with a "--language" flag + - Filter which Schema objects you’d like to include in your output with "--name" flags + - Combine your Schema objects into a single output with a "--flat" flag + - Omit import groups from your model with a "--no-imports" flag + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices schema datamodels [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to generate its data models + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -l, --language + - string + - false + - Specify the language to generate schema data models in (Default value: ) + * - --flat + - + - false + - View generated data models (and associated imports) as a single code block + * - --no-imports + - + - false + - View generated data models without imports + * - --name + - strings + - false + - Filter generated data models by name(s) + * - -h, --help + - + - false + - help for datamodels + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-schema.txt b/source/cli/appservices-schema.txt new file mode 100644 index 000000000..e60a9a358 --- /dev/null +++ b/source/cli/appservices-schema.txt @@ -0,0 +1,78 @@ +.. _appservices-schema: + +================== +appservices schema +================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Manage the Schemas of your app (alias: schemas) + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -h, --help + - + - false + - help for schema + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 + +Related Commands +---------------- + +* :ref:`appservices-schema-datamodels` - Generate data models based on your Schema (alias: datamodel) + + +.. toctree:: + :titlesonly: + + datamodels diff --git a/source/cli/appservices-secrets-create.txt b/source/cli/appservices-secrets-create.txt new file mode 100644 index 000000000..3cebc42d5 --- /dev/null +++ b/source/cli/appservices-secrets-create.txt @@ -0,0 +1,95 @@ +.. _appservices-secrets-create: + +========================== +appservices secrets create +========================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Create a Secret for your app + +You will be prompted to name your Secret and define the value of your Secret. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices secrets create [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to create its secrets + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -n, --name + - string + - false + - Name the secret + * - -v, --value + - string + - false + - Specify the secret value + * - -h, --help + - + - false + - help for create + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-secrets-delete.txt b/source/cli/appservices-secrets-delete.txt new file mode 100644 index 000000000..49eabe0da --- /dev/null +++ b/source/cli/appservices-secrets-delete.txt @@ -0,0 +1,93 @@ +.. _appservices-secrets-delete: + +========================== +appservices secrets delete +========================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Delete a Secret from your app + +With this command, you can: + - Remove multiple Secrets at once with "--secret" flags. You can specify these + Secrets using their ID or Name values + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices secrets delete [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to delete its secrets + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -s, --secret + - strings + - false + - Specify the name or ID of the secret to delete + * - -h, --help + - + - false + - help for delete + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-secrets-list.txt b/source/cli/appservices-secrets-list.txt new file mode 100644 index 000000000..6c2b31f88 --- /dev/null +++ b/source/cli/appservices-secrets-list.txt @@ -0,0 +1,87 @@ +.. _appservices-secrets-list: + +======================== +appservices secrets list +======================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +List the Secrets in your app (alias: ls) + +This will display the IDs and Names of the Secrets in your app. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices secrets list [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to list its secrets + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -h, --help + - + - false + - help for list + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-secrets-update.txt b/source/cli/appservices-secrets-update.txt new file mode 100644 index 000000000..4905278d4 --- /dev/null +++ b/source/cli/appservices-secrets-update.txt @@ -0,0 +1,100 @@ +.. _appservices-secrets-update: + +========================== +appservices secrets update +========================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Update a Secret in your app + +NOTE: The Name of the Secret cannot be modified. In order to do so, you will +need to delete and re-create the Secret. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices secrets update [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to update its secrets + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -s, --secret + - string + - false + - Specify the name or ID of the secret to update + * - -n, --name + - string + - false + - Re-name the secret + * - -v, --value + - string + - false + - Specify the new secret value + * - -h, --help + - + - false + - help for update + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-secrets.txt b/source/cli/appservices-secrets.txt new file mode 100644 index 000000000..26c2a6af6 --- /dev/null +++ b/source/cli/appservices-secrets.txt @@ -0,0 +1,84 @@ +.. _appservices-secrets: + +=================== +appservices secrets +=================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Manage the Secrets of your app (alias: secret) + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -h, --help + - + - false + - help for secrets + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 + +Related Commands +---------------- + +* :ref:`appservices-secrets-create` - Create a Secret for your app +* :ref:`appservices-secrets-delete` - Delete a Secret from your app +* :ref:`appservices-secrets-list` - List the Secrets in your app (alias: ls) +* :ref:`appservices-secrets-update` - Update a Secret in your app + + +.. toctree:: + :titlesonly: + + create + delete + list + update diff --git a/source/cli/appservices-users-create.txt b/source/cli/appservices-users-create.txt new file mode 100644 index 000000000..af70cd4ba --- /dev/null +++ b/source/cli/appservices-users-create.txt @@ -0,0 +1,104 @@ +.. _appservices-users-create: + +======================== +appservices users create +======================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Create an application user for your app + +Adds a new User to your app. You can create a User for the following enabled +Auth Providers: "Email/Password", or "API Key". + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices users create [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to create its users + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - --type + - string + - false + - Select the type of user to create (Default value: ; Allowed values: api-key, email) + * - --name + - string + - false + - Specify the name of the new API Key + * - --email + - string + - false + - Specify the email of the new user + * - --password + - string + - false + - Specify the password of the new user + * - -h, --help + - + - false + - help for create + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-users-delete.txt b/source/cli/appservices-users-delete.txt new file mode 100644 index 000000000..1c09a1e31 --- /dev/null +++ b/source/cli/appservices-users-delete.txt @@ -0,0 +1,104 @@ +.. _appservices-users-delete: + +======================== +appservices users delete +======================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Delete an application user from your app + +You can remove multiple Users at once with the "--user" flag. You can only +specify these Users using their ID values. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices users delete [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to delete its users + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -u, --user + - strings + - false + - Specify your app's users' ID(s) to delete + * - --pending + - + - false + - View the Realm app's pending users + * - --state + - string + - false + - Filter the Realm app's users by state (Default value: ; Allowed values: enabled, disabled) + * - --provider + - Set + - false + - Filter the Realm app's users by provider type (Default value: ; Allowed values: , "local-userpass", "api-key", "oauth2-facebook", "oauth2-google", "anon-user", "custom-token", "oauth2-apple", "custom-function") This value defaults to []. + * - -h, --help + - + - false + - help for delete + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-users-disable.txt b/source/cli/appservices-users-disable.txt new file mode 100644 index 000000000..68746e58d --- /dev/null +++ b/source/cli/appservices-users-disable.txt @@ -0,0 +1,92 @@ +.. _appservices-users-disable: + +========================= +appservices users disable +========================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Disable an application User of your app + +Deactivates a User on your app. A User that has been disabled will not be +allowed to log in, even if they provide valid credentials. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices users disable [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to disable its users + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -u, --user + - strings + - false + - Specify your app's users' ID(s) to disable + * - -h, --help + - + - false + - help for disable + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-users-enable.txt b/source/cli/appservices-users-enable.txt new file mode 100644 index 000000000..7e32afb7a --- /dev/null +++ b/source/cli/appservices-users-enable.txt @@ -0,0 +1,92 @@ +.. _appservices-users-enable: + +======================== +appservices users enable +======================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Enable an application User of your app + +Activates a User on your app. A User that has been enabled will have no +restrictions with logging in. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices users enable [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to enable its users’ + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -u, --user + - strings + - false + - Specify your app's users' ID(s) to enable + * - -h, --help + - + - false + - help for enable + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-users-list.txt b/source/cli/appservices-users-list.txt new file mode 100644 index 000000000..d37978fb4 --- /dev/null +++ b/source/cli/appservices-users-list.txt @@ -0,0 +1,104 @@ +.. _appservices-users-list: + +====================== +appservices users list +====================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +List the application users of your app (alias: ls) + +Displays a list of your app's Users' details. The list is grouped by Auth +Provider type and sorted by Last Authentication Date. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices users list [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to list its users’ + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -u, --user + - strings + - false + - Filter the App Service's users by ID(s) + * - --pending + - + - false + - View the Realm app's pending users + * - --state + - string + - false + - Filter the Realm app's users by state (Default value: ; Allowed values: enabled, disabled) + * - --provider + - Set + - false + - Filter the Realm app's users by provider type (Default value: ; Allowed values: , "local-userpass", "api-key", "oauth2-facebook", "oauth2-google", "anon-user", "custom-token", "oauth2-apple", "custom-function") This value defaults to []. + * - -h, --help + - + - false + - help for list + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-users-revoke.txt b/source/cli/appservices-users-revoke.txt new file mode 100644 index 000000000..0d119067e --- /dev/null +++ b/source/cli/appservices-users-revoke.txt @@ -0,0 +1,104 @@ +.. _appservices-users-revoke: + +======================== +appservices users revoke +======================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Revoke an application User's sessions from your app + +Logs a User out of your app. A revoked User can log in again if they provide +valid credentials. + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices users revoke [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -a, --app + - string + - false + - Specify the name or ID of an App Service to revoke its users' sessions + * - --project + - string + - false + - Specify the ID of a MongoDB Atlas project + * - -u, --user + - strings + - false + - Specify the app's users' ID(s) to revoke sessions for + * - --pending + - + - false + - View the Realm app's pending users + * - --state + - string + - false + - Filter the Realm app's users by state (Default value: ; Allowed values: enabled, disabled) + * - --provider + - Set + - false + - Filter the Realm app's users by provider type (Default value: ; Allowed values: , "local-userpass", "api-key", "oauth2-facebook", "oauth2-google", "anon-user", "custom-token", "oauth2-apple", "custom-function") This value defaults to []. + * - -h, --help + - + - false + - help for revoke + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/cli/appservices-users.txt b/source/cli/appservices-users.txt new file mode 100644 index 000000000..7e86e81d1 --- /dev/null +++ b/source/cli/appservices-users.txt @@ -0,0 +1,88 @@ +.. _appservices-users: + +================= +appservices users +================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Manage the Users of your app (alias: user) + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - -h, --help + - + - false + - help for users + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 + +Related Commands +---------------- + +* :ref:`appservices-users-create` - Create an application user for your app +* :ref:`appservices-users-delete` - Delete an application user from your app +* :ref:`appservices-users-disable` - Disable an application User of your app +* :ref:`appservices-users-enable` - Enable an application User of your app +* :ref:`appservices-users-list` - List the application users of your app (alias: ls) +* :ref:`appservices-users-revoke` - Revoke an application User’s sessions from your app + + +.. toctree:: + :titlesonly: + + create + delete + disable + enable + list + revoke diff --git a/source/cli/appservices-whoami.txt b/source/cli/appservices-whoami.txt new file mode 100644 index 000000000..22fbe545e --- /dev/null +++ b/source/cli/appservices-whoami.txt @@ -0,0 +1,87 @@ +.. _appservices-whoami: + +================== +appservices whoami +================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Display information about the current user + +Displays a table that includes your Public and redacted Private Atlas +programmatic API Key (e.g. ``********-****-****-****-3ba985aa367a``). No session +data will be surfaced if you are not logged in. + +NOTE: To log in and authenticate your session, use "appservices login" + +Syntax +------ + +.. code-block:: + :caption: Command Syntax + + appservices whoami [options] + +.. Code end marker, please don't delete this comment + +Options +------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --show-projects + - + - false + - Show projects associated with this profile's API Key + * - -h, --help + - + - false + - help for whoami + +Inherited Options +----------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - false + - Specify your profile (Default value: "default") + * - --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: ; Allowed values: , "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 diff --git a/source/data-api/custom-endpoints.txt b/source/data-api/custom-endpoints.txt index 9191916e7..da9acd015 100644 --- a/source/data-api/custom-endpoints.txt +++ b/source/data-api/custom-endpoints.txt @@ -107,7 +107,7 @@ Create a Custom HTTPS Endpoint ------------------------------ You can configure the Data API for your app from the App Services UI or by -deploying configuration files with Realm CLI: +deploying configuration files with {+cli+}: .. tabs-realm-admin-interfaces:: @@ -152,7 +152,7 @@ deploying configuration files with Realm CLI: .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" 2. Define a :ref:`configuration ` object for the custom endpoint. @@ -190,7 +190,7 @@ deploying configuration files with Realm CLI: .. code-block:: bash - realm-cli push + {+cli-bin+} push Authentication ~~~~~~~~~~~~~~ diff --git a/source/data-api/examples.txt b/source/data-api/examples.txt index 32c39bdc0..3385b7ee0 100644 --- a/source/data-api/examples.txt +++ b/source/data-api/examples.txt @@ -450,7 +450,7 @@ delete, or modify any data. To define roles for a specific collection, update the collection's configuration file with the :ref:`collection-specific role -configurations `: +configurations `: .. code-block:: json :caption: /data_sources////rules.json diff --git a/source/data-api/generated-endpoints.txt b/source/data-api/generated-endpoints.txt index 575beba39..c373f81f2 100644 --- a/source/data-api/generated-endpoints.txt +++ b/source/data-api/generated-endpoints.txt @@ -87,7 +87,7 @@ Set Up the Data API ------------------- You can configure the Data API for your app from the App Services UI or by -deploying configuration files with Realm CLI: +deploying configuration files with {+cli+}: .. tabs-realm-admin-interfaces:: @@ -120,7 +120,7 @@ deploying configuration files with Realm CLI: .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" 2. Define a Data API configuration file. @@ -138,7 +138,7 @@ deploying configuration files with Realm CLI: .. code-block:: bash - realm-cli push + {+cli-bin+} push .. _data-api-authentication: diff --git a/source/functions.txt b/source/functions.txt index bfb69329e..c32861468 100644 --- a/source/functions.txt +++ b/source/functions.txt @@ -364,7 +364,7 @@ or by importing the function configuration and source code with .. code-block:: shell - realm-cli pull --remote= + {+cli-bin+} pull --remote= .. step:: Write the Function Source Code @@ -526,7 +526,7 @@ or by importing the function configuration and source code with .. code-block:: shell - realm-cli push + {+cli-bin+} push Call a Function @@ -563,18 +563,18 @@ runs in the same context as the function that called it. return context.functions.execute("sum", a, -1 * b); }; -.. _call-function-from-realm-cli: +.. _call-function-cli: Call from {+cli+} -~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~ You can call a function through {+cli+} with the :ref:`function run -` command. The command returns the function +` command. The command returns the function result as EJSON as well as any log or error messages. .. code-block:: sh - realm-cli function run \ + {+cli-bin+} function run \ --function=sum \ --args=1 --args=2 @@ -585,7 +585,7 @@ user, include their User ID in the ``--user`` argument. .. code-block:: sh :emphasize-lines: 4 - realm-cli function run \ + {+cli-bin+} function run \ --function=sum \ --args=1 --args=2 \ --user=61a50d82532cbd0de95c7c89 diff --git a/source/functions/dependencies.txt b/source/functions/dependencies.txt index 0fa575ad6..8f970513b 100644 --- a/source/functions/dependencies.txt +++ b/source/functions/dependencies.txt @@ -119,7 +119,7 @@ name. You can either add a specific version or use the latest version. .. code-block:: - realm-cli pull + {+cli-bin+} pull .. step:: Create a package.json File with Dependencies @@ -142,7 +142,7 @@ name. You can either add a specific version or use the latest version. .. code-block:: - realm-cli push --include-package-json + {+cli-bin+} push --include-package-json #. Follow the CLI prompts to confirm that you want to include the dependencies in your operation. The CLI will start adding the dependencies to your App. @@ -173,7 +173,7 @@ name. You can either add a specific version or use the latest version. .. code-block:: - realm-cli pull + {+cli-bin+} pull .. step:: Create a package.json File with Dependencies @@ -259,7 +259,7 @@ app. Zipped dependency directories may not exceed 15MB. .. step:: Upload the Dependency Archive Once you've created an archive containing your dependencies, you can upload your - dependency archive using the App Services UI or {+cli-bin+}: + dependency archive using the App Services UI or the {+cli+}: .. tabs-realm-admin-interfaces:: @@ -301,8 +301,7 @@ app. Zipped dependency directories may not exceed 15MB. .. code-block:: shell - realm-cli push --include-node-modules - + {+cli-bin+} push --include-node-modules .. _import-external-dependencies: diff --git a/source/functions/handle-errors.txt b/source/functions/handle-errors.txt index 933e8c6a5..061a0de43 100644 --- a/source/functions/handle-errors.txt +++ b/source/functions/handle-errors.txt @@ -203,10 +203,10 @@ execution tracker collection, and Database Trigger Function. .. tab:: :tabid: cli - .. tip:: Install and Set up Realm CLI + .. tip:: Install and Set up {+cli+} - If you're using the Realm CLI to update your App Services App, - you must first :ref:`install and set up the Realm CLI `. + If you're using the CLI to update your App Services App, + you must first install and set up the {+cli-ref+}. Add the following to :file:`functions/config.json`: @@ -232,7 +232,7 @@ execution tracker collection, and Database Trigger Function. .. code-block:: sh - realm-cli push + {+cli-bin+} push .. step:: Create retry database trigger @@ -350,7 +350,7 @@ execution tracker collection, and Database Trigger Function. .. code-block:: sh - realm-cli push + {+cli-bin+} push .. step:: Write Function to retry @@ -469,7 +469,7 @@ execution tracker collection, and Database Trigger Function. .. code-block:: sh - realm-cli push + {+cli-bin+} push Now when you invoke ``additionWithRetryHandler``, the Function will retry if it fails. diff --git a/source/functions/test.txt b/source/functions/test.txt index d096b4ac6..a68110f77 100644 --- a/source/functions/test.txt +++ b/source/functions/test.txt @@ -20,9 +20,11 @@ the uniqueness of Functions. Before You Begin ---------------- -#. :ref:`Create an Atlas App Services App ` -#. :ref:`Configure the CLI to work with your App ` or - :ref:`automate deployment with Github ` +You will need the following to test an Atlas Function: + +- .. include:: /includes/prereqs/app.rst + +- .. include:: /includes/prereqs/code-deploy.rst .. _unit-test-functions: @@ -49,7 +51,7 @@ Functions. .. code-block:: sh - realm-cli pull --remote + {+cli-bin+} pull --remote .. tab:: Github :tabid: github diff --git a/source/hosting/configure-file-metadata.txt b/source/hosting/configure-file-metadata.txt index d1640b3d3..c85fc50e5 100644 --- a/source/hosting/configure-file-metadata.txt +++ b/source/hosting/configure-file-metadata.txt @@ -76,7 +76,7 @@ Procedure .. code-block:: shell - realm-cli pull --remote= + {+cli-bin+} pull --remote= .. step:: Add Attributes to the Metadata Configuration File @@ -115,5 +115,4 @@ Procedure .. code-block:: shell - realm-cli push --include-hosting - + {+cli-bin+} push --include-hosting diff --git a/source/hosting/enable-hosting.txt b/source/hosting/enable-hosting.txt index 6b110809c..5dc57ef9a 100644 --- a/source/hosting/enable-hosting.txt +++ b/source/hosting/enable-hosting.txt @@ -93,14 +93,14 @@ Enable hosting from the UI with the following procedure: .. .. step:: Pull the Latest Version of Your App -.. To enable static hosting with {+cli-bin+}, you need a local copy of your +.. To enable static hosting with the {+cli-ref+}, you need a local copy of your .. application's configuration files. .. To pull a local copy of the latest version of your app, run the following: .. .. code-block:: bash -.. realm-cli pull --remote="" +.. {+cli-bin+} pull --remote="" .. .. tip:: @@ -125,7 +125,7 @@ Enable hosting from the UI with the following procedure: .. .. code-block:: bash -.. realm-cli push --remote=" --include-hosting" +.. {+cli-bin+} push --remote=" --include-hosting" .. .. note:: diff --git a/source/hosting/flush-the-cdn-cache.txt b/source/hosting/flush-the-cdn-cache.txt index ad988e9e5..7f48e51b4 100644 --- a/source/hosting/flush-the-cdn-cache.txt +++ b/source/hosting/flush-the-cdn-cache.txt @@ -82,14 +82,14 @@ Procedure .. step:: Pull the Latest Version of Your App - To purge the CDN cache with {+cli-bin+}, you need a local copy of your + To purge the CDN cache with the {+cli-ref+}, you need a local copy of your application's configuration files. To pull a local copy of the latest version of your app, run the following: .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" .. tip:: @@ -104,5 +104,4 @@ Procedure .. code-block:: bash - realm-cli push --remote="" --reset-cdn-cache - + {+cli-bin+} push --remote="" --reset-cdn-cache diff --git a/source/hosting/host-a-single-page-application.txt b/source/hosting/host-a-single-page-application.txt index 630794ba6..822072f24 100644 --- a/source/hosting/host-a-single-page-application.txt +++ b/source/hosting/host-a-single-page-application.txt @@ -89,14 +89,14 @@ Procedure .. step:: Pull the Latest Version of Your App - To configure a single-page application with {+cli-bin+}, you need a local copy + To configure a single-page application with the {+cli-ref+}, you need a local copy of your application's configuration files. To pull a local copy of the latest version of your app, run the following: .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" .. tip:: @@ -141,5 +141,4 @@ Procedure .. code-block:: bash - realm-cli push --remote="" --include-hosting - + {+cli-bin+} push --remote="" --include-hosting diff --git a/source/hosting/upload-content-to-app-services.txt b/source/hosting/upload-content-to-app-services.txt index 2f8e29ee3..598245ac2 100644 --- a/source/hosting/upload-content-to-app-services.txt +++ b/source/hosting/upload-content-to-app-services.txt @@ -67,7 +67,7 @@ Procedure .. code-block:: shell - realm-cli pull --remote= + {+cli-bin+} pull --remote= .. step:: Add a Hosting Directory @@ -83,7 +83,7 @@ Procedure .. step:: Add a Metadata Configuration File - To deploy hosted files through {+cli-bin+} you must include a + To deploy hosted files through the {+cli-ref+} you must include a ``metadata.json`` file in the ``/hosting`` directory. If the configuration file does not exist, create it: @@ -125,7 +125,7 @@ Procedure .. code-block:: shell - realm-cli push --include-hosting + {+cli-bin+} push --include-hosting .. note:: diff --git a/source/hosting/use-a-custom-404-page.txt b/source/hosting/use-a-custom-404-page.txt index 5fafc9111..173da97f9 100644 --- a/source/hosting/use-a-custom-404-page.txt +++ b/source/hosting/use-a-custom-404-page.txt @@ -74,14 +74,14 @@ Procedure .. step:: Pull the Latest Version of Your App - To configure a custom 404 page with {+cli-bin+}, you need a local copy of your + To configure a custom 404 page with the {+cli-ref+}, you need a local copy of your application's configuration files. To pull a local copy of the latest version of your app, run the following: .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" .. tip:: @@ -131,4 +131,4 @@ Procedure .. code-block:: bash - realm-cli push --remote="" --include-hosting + {+cli-bin+} push --remote="" --include-hosting diff --git a/source/hosting/use-a-custom-domain-name.txt b/source/hosting/use-a-custom-domain-name.txt index e414c7fea..5dc04983e 100644 --- a/source/hosting/use-a-custom-domain-name.txt +++ b/source/hosting/use-a-custom-domain-name.txt @@ -142,14 +142,14 @@ Procedure .. step:: Pull the Latest Version of Your App - To configure a custom domain name with {+cli-bin+}, you need a local copy of + To configure a custom domain name with the {+cli-ref+}, you need a local copy of your application's configuration files. To pull a local copy of the latest version of your app, run the following: .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" .. tip:: @@ -187,7 +187,7 @@ Procedure .. code-block:: shell - realm-cli import --include-hosting + {+cli-bin+} import --include-hosting .. step:: Deploy the Updated Hosting Configuration @@ -198,7 +198,7 @@ Procedure .. code-block:: bash - realm-cli push --remote="" --include-hosting + {+cli-bin+} push --remote="" --include-hosting .. step:: Add a Validation CNAME Record diff --git a/source/includes/app-services-cli-overview.rst b/source/includes/app-services-cli-overview.rst new file mode 100644 index 000000000..ca35d07cd --- /dev/null +++ b/source/includes/app-services-cli-overview.rst @@ -0,0 +1,160 @@ +.. _cli-overview: + +Overview +-------- + +The Atlas App Services Command Line Interface (``{+cli-bin+}``) allows you +to programmatically manage your Applications. + +With the {+cli+}, you can create or update Apps from a local directory +as well as export existing applications to a local directory. + +.. _install-appservices-cli: + +Installation +------------ + +.. include:: /includes/install-appservices-cli.rst + +.. _cli-auth-with-api-token: + +Authentication +-------------- + +To use the {+cli+}, you must authenticate. To authenticate, you must +generate an API Key. + +Generate an API Key +~~~~~~~~~~~~~~~~~~~ + +.. procedure:: + + .. step:: Navigate to MongoDB Cloud Access Manager + + The :mms-docs:`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 + :guilabel:`Project Access` tab on the :guilabel:`access manager + dropdown` on your screen's top left-hand side. + + .. figure:: /images/click-access-manager.png + :alt: Click Access Manager + :lightbox: + + + .. step:: Create an API Key + + Project Users can log in with a Project API Key. Create a project + API Key by clicking the grey :guilabel:`Create API Key` button on + the right-hand side of the Project Access Manager. + + .. figure:: /images/access-manager-create-api-key-button.png + :alt: Click Access Manager + :lightbox: + + 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 + :guilabel:`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 :guilabel:`next` to + continue configuring your key details. + + .. figure:: /images/configure-api-key.png + :alt: Click Access Manager + :lightbox: + + + .. step:: 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 :guilabel:`Add Access List Entry` button. + Type in the IP Address or click the :guilabel:`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. + + .. figure:: /images/add-access-list-entry.png + :alt: Click Access Manager + :lightbox: + +Authenticate with an API Key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. procedure:: + + .. step:: Authenticate a CLI User + + Using your newly created public and private key, log in by running the + command below. + + .. code-block:: shell + + {+cli-bin+} login --api-key="" --private-api-key="" + + You should see the following result: + + .. code-block:: shell + + you have successfully logged in as + +.. _dot-mdb: + +The ``.mdb`` Directory +---------------------- + +When you use the {+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: + +.. code-block:: json + + { + "config_version": 20230101, + "app_id": "42249d526d97af5a287c1eae", + "group_id": "4b2cf422930196872221a2d4", + "client_app_id": "myapp-abcde" + } + +.. list-table:: + :header-rows: 1 + + * - 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. diff --git a/source/includes/appschema-mongodb.rst b/source/includes/appschema-mongodb.rst index b19c2f5e6..bf7d86686 100644 --- a/source/includes/appschema-mongodb.rst +++ b/source/includes/appschema-mongodb.rst @@ -163,7 +163,7 @@ evaluates dynamically for each request. Each collection's rules are stored in a * - | ``roles`` | Array - An array of :ref:`Role configuration documents - `, which have the following form: + `, which have the following form: .. include:: /mongodb/tables/role-configuration.rst @@ -185,6 +185,6 @@ evaluates dynamically for each request. Each collection's rules are stored in a * - | ``filters`` | Array - An array of :ref:`Filter configuration documents - `, which have the following form: + `, which have the following form: .. include:: /mongodb/tables/query-filter-params.rst diff --git a/source/includes/cli-login.rst b/source/includes/cli-login.rst index 62b599d1c..dfb900b33 100644 --- a/source/includes/cli-login.rst +++ b/source/includes/cli-login.rst @@ -2,4 +2,4 @@ Use your MongoDB Atlas Admin API Key to log in to the CLI: .. code-block:: shell - realm-cli login --api-key="" --private-api-key="" + {+cli-bin+} login --api-key="" --private-api-key="" diff --git a/source/includes/cli-pull-latest.rst b/source/includes/cli-pull-latest.rst index 405d6905a..11d2e97ea 100644 --- a/source/includes/cli-pull-latest.rst +++ b/source/includes/cli-pull-latest.rst @@ -3,7 +3,7 @@ version of your App, run the following command: .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" You can also export a copy of your application's configuration files from the UI or with the Admin API. To learn how, see :ref:`Export an App diff --git a/source/includes/install-appservices-cli.rst b/source/includes/install-appservices-cli.rst new file mode 100644 index 000000000..93264f850 --- /dev/null +++ b/source/includes/install-appservices-cli.rst @@ -0,0 +1,7 @@ +{+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: + +.. code-block:: shell + + npm install -g atlas-app-services-cli diff --git a/source/includes/install-realm-cli-v1.rst b/source/includes/install-realm-cli-v1.rst index 403c3e462..72f6e845c 100644 --- a/source/includes/install-realm-cli-v1.rst +++ b/source/includes/install-realm-cli-v1.rst @@ -1,7 +1,8 @@ -{+cli+} is available on ``npm``. To install version 1 of the {+cli+} on your -system, ensure that you have `Node.js `_ -installed and then run the following command in your shell: +``realm-cli`` is available on ``npm``. To install version 1 of the +``realm-cli`` on your system, ensure that you have `Node.js +`_ installed and then run the following +command in your shell: .. code-block:: shell - npm install -g mongodb-realm-cli@1.3.4 + npm install -g mongodb-realm-cli@^1 diff --git a/source/includes/install-realm-cli-v2.rst b/source/includes/install-realm-cli-v2.rst index 133e443cf..85b49ce6d 100644 --- a/source/includes/install-realm-cli-v2.rst +++ b/source/includes/install-realm-cli-v2.rst @@ -1,6 +1,7 @@ -{+cli+} is available on ``npm``. To install version 2 of the {+cli+} on your -system, ensure that you have `Node.js `_ -installed and then run the following command in your shell: +``realm-cli`` is available on ``npm``. To install version 2 of the +``realm-cli`` on your system, ensure that you have `Node.js +`_ installed and then run the following +command in your shell: .. code-block:: shell diff --git a/source/includes/note-procedure-uses-cli-v2.rst b/source/includes/note-procedure-uses-cli-v2.rst deleted file mode 100644 index 6d678ace0..000000000 --- a/source/includes/note-procedure-uses-cli-v2.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. important:: Check your CLI version - - This procedure uses version 2 of {+cli+}. If you have an older version of - {+cli+}, upgrade to the latest version or run {+cli-bin+} ``--help`` for a - list of commands supported in your version. diff --git a/source/includes/prereqs/app-services-cli.rst b/source/includes/prereqs/app-services-cli.rst deleted file mode 100644 index d6c82b2a2..000000000 --- a/source/includes/prereqs/app-services-cli.rst +++ /dev/null @@ -1,2 +0,0 @@ -{+cli+} :ref:`installed ` and added to your system -``PATH``. diff --git a/source/includes/prereqs/app.rst b/source/includes/prereqs/app.rst new file mode 100644 index 000000000..a52b6d058 --- /dev/null +++ b/source/includes/prereqs/app.rst @@ -0,0 +1,2 @@ +An Atlas App Services App. To learn how to create one, see :ref:`Create +an App `. diff --git a/source/includes/prereqs/appservices-cli.rst b/source/includes/prereqs/appservices-cli.rst new file mode 100644 index 000000000..57a034830 --- /dev/null +++ b/source/includes/prereqs/appservices-cli.rst @@ -0,0 +1,2 @@ +A copy of {+cli+} installed and added to your local system ``PATH``. To +learn how, see :ref:`Install {+cli+} `. diff --git a/source/includes/prereqs/code-deploy.rst b/source/includes/prereqs/code-deploy.rst new file mode 100644 index 000000000..8bfcfcc55 --- /dev/null +++ b/source/includes/prereqs/code-deploy.rst @@ -0,0 +1,5 @@ +A code deploy method to configure your App. Choose one of: + +- .. include:: /includes/prereqs/appservices-cli.rst + +- .. include:: /includes/prereqs/github-deployment.rst diff --git a/source/includes/prereqs/github-deployment.rst b/source/includes/prereqs/github-deployment.rst new file mode 100644 index 000000000..e99d21f8a --- /dev/null +++ b/source/includes/prereqs/github-deployment.rst @@ -0,0 +1,3 @@ +A GitHub repository configured to hold and deploy configuration files +for your App. To learn how to set one up, see :ref:`Deploy Automatically +with GitHub `. diff --git a/source/includes/realm-cli-deprecation.rst b/source/includes/realm-cli-deprecation.rst new file mode 100644 index 000000000..f6dfe494f --- /dev/null +++ b/source/includes/realm-cli-deprecation.rst @@ -0,0 +1,6 @@ +.. important:: Realm CLI is Deprecated + + ``realm-cli`` is deprecated and will not receive future features or + bug fixes. Instead, use the {+cli-ref+}. + + .. include:: /includes/install-appservices-cli.rst diff --git a/source/includes/template-app-custom-user-data-workaround.rst b/source/includes/template-app-custom-user-data-workaround.rst index 416b21549..a1d6afbad 100644 --- a/source/includes/template-app-custom-user-data-workaround.rst +++ b/source/includes/template-app-custom-user-data-workaround.rst @@ -1,6 +1,6 @@ **Custom User Data Configuration Bug Workaround:** Sometimes, the template generator does not copy the custom user data configuration to the new app -correctly. You can fix this as follows: the ``realm-cli apps create`` command +correctly. You can fix this as follows: the ``{+cli-bin+} apps create`` command should have output some JSON about the app you just created. From this JSON, copy the "url" value (something like ``https://realm.mongodb.com/groups/...``) and visit that URL in your browser. Log in if prompted. From the app dashboard, diff --git a/source/includes/tutorial-template-prerequisite.rst b/source/includes/tutorial-template-prerequisite.rst index 484e6326e..ea0206f7b 100644 --- a/source/includes/tutorial-template-prerequisite.rst +++ b/source/includes/tutorial-template-prerequisite.rst @@ -1,16 +1,18 @@ - This tutorial starts with a Template App. You need an `Atlas Account `_, an API key, and - ``realm-cli`` to create a Template App. + {+cli-bin+} to create a Template App. - You can learn more about creating an Atlas account in the :atlas:`Atlas Getting Started ` documentation. For this tutorial, you need an Atlas account with a free-tier cluster. - - You also need an Atlas :atlas:`API key ` - for the MongoDB Cloud account you wish to log in with. - You must be a :atlas:`Project Owner ` - to create a Template App using ``realm-cli``. + - You also need an Atlas :atlas:`API key + ` for the MongoDB + Cloud account you wish to log in with. You must be a :atlas:`Project + Owner ` to create a Template + App using {+cli-bin+}. - - To learn more about installing ``realm-cli``, see - :ref:`Install realm-cli `. After you have installed ``realm-cli``, - :ref:`login ` using the API key for your Atlas project. \ No newline at end of file + - To learn more about installing {+cli-bin+}, see :ref:`Install App + Services CLI `. After installing, run the + :ref:`login ` command using the API key for + your Atlas project. diff --git a/source/logs/cli.txt b/source/logs/cli.txt new file mode 100644 index 000000000..baa7dbe27 --- /dev/null +++ b/source/logs/cli.txt @@ -0,0 +1,74 @@ +=============================== +View Logs with {+cli+} +=============================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +View Recent Logs +---------------- + +You can list the 100 most recent log entries for your application: + +.. code-block:: shell + + {+cli-bin+} logs list + +Tail Logs in Real Time +---------------------- + +You can use the ``--tail`` flag to open a stream that displays application logs +as they come in. + +.. code-block:: shell + + {+cli-bin+} logs list --tail + +View Error Logs +--------------- + +You can use the ``--errors`` flag to view only error logs. If you don't specify +the flag, the command returns both error logs and regular logs. + +.. code-block:: shell + + {+cli-bin+} logs list --errors + +Filter Logs by Type +------------------- + +You can use the ``--type`` flag to view logs of one or more specific types. If +you don't specify a type, the command returns logs of all types. + +The following types are valid: + +- ``auth`` +- ``function`` +- ``push`` +- ``service`` +- ``trigger`` +- ``graphql`` +- ``sync`` +- ``schema`` + +.. code-block:: shell + + {+cli-bin+} logs list --type=function --type=trigger + +.. _cli-view-logs-for-date-range: + +View Logs for a Date Range +-------------------------- + +You can use the ``--start`` and ``--end`` flags to view logs from a range of +dates. The flags accept ISODate strings and you can use them separately or +together. + +.. code-block:: shell + + {+cli-bin+} logs list --start="2021-01-01T00:00:00.000+0000" --end="2021-02-01T00:00:00.000+0000" diff --git a/source/mongodb.txt b/source/mongodb.txt index 7f8461ac2..d7df5a715 100644 --- a/source/mongodb.txt +++ b/source/mongodb.txt @@ -144,7 +144,7 @@ and even create multiple data sources that link to the same underlying instance. You can configure a new linked data source in the App Services UI or by defining -and pushing a configuration file with {+cli+} or GitHub deployment: +and pushing a configuration file with the {+cli-ref+} or GitHub deployment: .. tabs-realm-admin-interfaces:: @@ -217,14 +217,14 @@ and pushing a configuration file with {+cli+} or GitHub deployment: .. step:: Pull the Latest Version of Your App - To link a MongoDB Atlas cluster or {+adf-instance+} with {+cli-bin+}, you need a + To link a MongoDB Atlas cluster or {+adf-instance+} with the {+cli+}, you need a local copy of your application's configuration files. To pull a local copy of the latest version of your app, run the following: .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" .. tip:: @@ -302,7 +302,7 @@ and pushing a configuration file with {+cli+} or GitHub deployment: .. code-block:: bash - realm-cli push --remote="" + {+cli-bin+} push --remote="" Data Source Limitations diff --git a/source/mongodb/configure-advanced-rules.txt b/source/mongodb/configure-advanced-rules.txt index b00d196d4..59627fa09 100644 --- a/source/mongodb/configure-advanced-rules.txt +++ b/source/mongodb/configure-advanced-rules.txt @@ -104,7 +104,10 @@ Procedure - Description * - ``roles`` - - An array of :ref:`Role configuration documents ` that each define a single role's :guilabel:`Apply When` condition and associated CRUD permissions. + - An array of :ref:`Role configuration documents + ` that each define a single role's + :guilabel:`Apply When` condition and associated CRUD + permissions. .. important:: @@ -114,7 +117,7 @@ Procedure evaluation order. * - ``filters`` - - An array of :ref:`Filter configuration documents ` that each define a filter on the collection. + - An array of :ref:`Filter configuration documents ` that each define a filter on the collection. * - ``schema`` - A :ref:`schema ` that configures the shape and contents of all documents in the collection. @@ -136,4 +139,3 @@ Procedure :guilabel:`Save Draft` in the top right corner. App Services will immediately begin using the new rule configuration you defined for all incoming queries on the collection. - diff --git a/source/mongodb/read-preference.txt b/source/mongodb/read-preference.txt index 400f85dfc..25e17b95a 100644 --- a/source/mongodb/read-preference.txt +++ b/source/mongodb/read-preference.txt @@ -119,14 +119,14 @@ Procedure .. step:: Pull the Latest Version of Your App - To define the read preference for a linked cluster with {+cli-bin+}, you need + To define the read preference for a linked cluster with the {+cli-ref+}, you need a local copy of your application's configuration files. To pull a local copy of the latest version of your app, run the following: .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" .. tip:: @@ -199,4 +199,4 @@ Procedure .. code-block:: bash - realm-cli push --remote="" + {+cli-bin+} push --remote="" diff --git a/source/mongodb/tables/query-filter-params.rst b/source/mongodb/tables/query-filter-params.rst index e7472c7da..b8cff38bf 100644 --- a/source/mongodb/tables/query-filter-params.rst +++ b/source/mongodb/tables/query-filter-params.rst @@ -15,20 +15,20 @@ - Description * - | ``name`` - | String + | ``string`` - Required. The name of the filter. Filter names are useful for identifying and distinguishing between filters. Limited to 100 characters or fewer. * - | ``apply_when`` - | Expression + | ``object`` - An :ref:`expression ` that determines when this filter applies to an incoming MongoDB operation. .. include:: /includes/note-filters-no-mongodb-expansions.rst * - | ``query`` - | Object + | ``object`` | *Default:* ``{}`` - A :manual:`MongoDB query ` that App Services merges into a filtered operation's existing query. @@ -43,7 +43,7 @@ { "score": { "$gte": 20 } } * - | ``projection`` - | Object + | ``object`` | *Default:* ``{}`` - A :manual:`MongoDB projection ` that App Services merges into a filtered operation's existing projection. diff --git a/source/mongodb/tables/role-configuration.rst b/source/mongodb/tables/role-configuration.rst index 0617530ea..b09767abf 100644 --- a/source/mongodb/tables/role-configuration.rst +++ b/source/mongodb/tables/role-configuration.rst @@ -34,12 +34,12 @@ - Description * - | ``name`` - | string + | ``string`` - The name of the role. Role names identify and distinguish between roles in the same collection. Limited to 100 characters or fewer. * - | ``apply_when`` - | Expression + | ``object`` - An :ref:`expression ` that evaluates to true when this :ref:`role ` applies to a user. @@ -87,7 +87,7 @@ } * - | ``document_filters.read`` - | Expression + | ``object?`` | *Default:* ``undefined`` - An :ref:`expression ` that specifies whether ``read``, read permissions in ``fields``, and read permissions in ``additional_fields`` @@ -99,7 +99,7 @@ `. * - | ``document_filters.write`` - | Expression + | ``object?`` | *Default:* ``undefined`` - An :ref:`expression ` that specifies whether ``write``, write permissions in ``fields``, and write permissions in @@ -111,7 +111,7 @@ `. * - | ``read`` - | Expression + | ``object?`` | *Default:* ``undefined`` - An :ref:`expression ` that evaluates to true if the role has permission to read all fields in the document. @@ -129,7 +129,7 @@ undefined and use ``additional_fields``. * - | ``write`` - | Expression + | ``object?`` | *Default:* ``undefined`` - An :ref:`expression ` that evaluates to true if the role has permission to add, modify, or remove all fields in the document. @@ -156,7 +156,7 @@ explicitly defined. * - | ``insert`` - | Expression + | ``object?`` | *Default:* ``true`` - An :ref:`expression ` that evaluates to ``true`` if the role has permission to insert a new document into the @@ -167,7 +167,7 @@ fields in the new document. * - | ``delete`` - | Expression + | ``object?`` | *Default:* ``true`` - An :ref:`expression ` that evaluates to true if the role has permission to delete a document from the collection. @@ -218,7 +218,7 @@ document's embedded fields. * - | ``fields..read`` - | Expression + | ``object?`` | *Default:* ``false`` - An :ref:`expression ` that evaluates to true if the role has permission to read the field. @@ -227,7 +227,7 @@ expression must be a boolean literal (either ``true`` or ``false``). * - | ``fields..write`` - | Expression + | ``object?`` | *Default:* ``false`` - An :ref:`expression ` that evaluates to true if the role has permission to add, modify, or remove the field. @@ -266,7 +266,7 @@ } * - | ``additional_fields.read`` - | Expression + | ``object?`` | *Default:* ``false`` - An :ref:`expression ` that evaluates to true if the role has permission to read any field that does not have a field-level @@ -276,7 +276,7 @@ expression must be boolean (either ``true`` or ``false``). * - | ``additional_fields.write`` - | Expression + | ``object?`` | *Default:* ``false`` - An :ref:`expression ` that evaluates to true if the role has permission to add, modify, or remove any field that does not diff --git a/source/mongodb/wire-protocol.txt b/source/mongodb/wire-protocol.txt index 256eddb29..7bb9aab0f 100644 --- a/source/mongodb/wire-protocol.txt +++ b/source/mongodb/wire-protocol.txt @@ -297,14 +297,14 @@ you can connect to an App Services App with a connection string. .. step:: Pull the Latest Version of Your App - To enable MongoDB wire protocol connections with {+cli-bin+}, you need a local + To enable MongoDB wire protocol connections with the {+cli-ref+}, you need a local copy of your application's configuration files. To pull a local copy of the latest version of your app, run the following: .. code-block:: bash - realm-cli pull --remote="" + {+cli-bin+} pull --remote="" .. tip:: @@ -341,7 +341,7 @@ you can connect to an App Services App with a connection string. .. code-block:: bash - realm-cli push --remote="" + {+cli-bin+} push --remote="" .. _wire-protocol-connect: diff --git a/source/openapi-admin-v3.yaml b/source/openapi-admin-v3.yaml index 1f0fa9cda..3c344ccf2 100644 --- a/source/openapi-admin-v3.yaml +++ b/source/openapi-admin-v3.yaml @@ -8300,7 +8300,7 @@ tags: draft in the UI, your UI draft will become invalid and you will not be able to deploy it. You can download your UI draft by reviewing the draft in the `Deployment` page. You can use the download to deploy your - changes in the `realm-cli` or as a reference as you reapply changes in + changes in the `appservices` CLI or as a reference as you reapply changes in the UI. - name: data-api x-displayName: Data API diff --git a/source/realm-cli.txt b/source/realm-cli.txt new file mode 100644 index 000000000..e4a6c1fcc --- /dev/null +++ b/source/realm-cli.txt @@ -0,0 +1,22 @@ +========================== +``realm-cli`` [Deprecated] +========================== + +.. include:: /includes/realm-cli-deprecation.rst + +The MongoDB Realm Command Line Interface (``realm-cli``) allows you to +programmatically manage your App Services Apps. With ``realm-cli``, you +can create or update Apps from a local directory as well as export +existing applications to a local directory. + +There are two versions of ``realm-cli``. Find the appropriate version +for your use case below: + +- :ref:`realm-cli@^1 ` +- :ref:`realm-cli@^2 ` + +.. toctree:: + :titlesonly: + + realm-cli v1 + realm-cli v2 diff --git a/source/cli/realm-cli-reference-v1/index.txt b/source/realm-cli/v1.txt similarity index 92% rename from source/cli/realm-cli-reference-v1/index.txt rename to source/realm-cli/v1.txt index 70f5506b0..de15278b2 100644 --- a/source/cli/realm-cli-reference-v1/index.txt +++ b/source/realm-cli/v1.txt @@ -6,9 +6,9 @@ .. _realm-cli-v1: -============ -{+cli+} v1 -============ +============================= +``realm-cli`` v1 [Deprecated] +============================= .. default-domain:: mongodb @@ -18,15 +18,17 @@ :depth: 2 :class: singlecol +.. include:: /includes/realm-cli-deprecation.rst + Overview -------- .. program:: realm-cli .. binary:: realm-cli-v1 -The Atlas App Services Command Line Interface ({+cli-bin+}) +The Atlas App Services Command Line Interface (``realm-cli``) allows you to programmatically manage your Apps. -With {+cli-bin+}, you can create or update +With ``realm-cli``, you can create or update Apps from a local directory as well as export existing applications to a local directory. @@ -45,11 +47,11 @@ General Options .. important:: Check your CLI version This page documents commands, arguments, and flags for version 1 of - {+cli-bin+}. If you have a newer version of {+cli+}, run {+cli-bin+} - ``--help`` for a list of updated commands and usage examples. To check + ``realm-cli``. If you have a newer version of ``realm-cli``, run ``realm-cli`` + ``--help`` for a list of updated commands and usage examples. To check your CLI version, use: ``realm-cli --version``. -The following options are available for all {+cli-bin+} commands: +The following options are available for all ``realm-cli`` commands: .. option:: --config-path @@ -75,7 +77,7 @@ The following options are available for all {+cli-bin+} commands: | **Optional.** - If specified, suppress all text color in {+cli-bin+} output. + If specified, suppress all text color in ``realm-cli`` output. By default, some output such as errors and import diffs are colorized. Use this flag if you wish to prevent this behavior. @@ -85,7 +87,7 @@ The following options are available for all {+cli-bin+} commands: | **Optional.** If specified, automatically respond affirmatively to any yes/no prompts from - {+cli-bin+}. + ``realm-cli``. Authentication -------------- @@ -160,7 +162,7 @@ on the next line in the following format: [API Key: ********-****-****-****-] -If no user is logged in, {+cli-bin+} will return the following +If no user is logged in, ``realm-cli`` will return the following message: .. code-block:: shell @@ -180,7 +182,7 @@ Import an Application Use ``realm-cli import`` to import a local application directory into a hosted App. If you import a directory into an application -that doesn't exist, {+cli-bin+} can :ref:`create the application +that doesn't exist, ``realm-cli`` can :ref:`create the application ` for you. .. tip:: @@ -203,14 +205,14 @@ that doesn't exist, {+cli-bin+} can :ref:`create the application The Application ID of your App. - If not specified, {+cli-bin+} will attempt to use the value of + If not specified, ``realm-cli`` will attempt to use the value of ``app_id`` defined in :ref:`config.json `. If - ``config.json`` does not have an ``app_id`` value, {+cli-bin+} + ``config.json`` does not have an ``app_id`` value, ``realm-cli`` prompts you to create a new application. .. note:: New Application App IDs - If you create a new application with {+cli-bin+}, App Services + If you create a new application with ``realm-cli``, App Services generates a new App ID and ignores any value that you specify for the ``--app-id`` flag. @@ -222,7 +224,7 @@ that doesn't exist, {+cli-bin+} can :ref:`create the application The directory must contain, at minimum, a valid :ref:`config.json ` file. - If the ``path`` argument is omitted, {+cli-bin+} will search for a + If the ``path`` argument is omitted, ``realm-cli`` will search for a ``config.json`` file in the current application directory. .. option:: --strategy ['merge|replace|replace-by-name'] @@ -231,7 +233,7 @@ that doesn't exist, {+cli-bin+} can :ref:`create the application | **Default:** Merge The :ref:`import strategy ` that - {+cli-bin+} should use when reconciling imported entities. + ``realm-cli`` should use when reconciling imported entities. .. option:: --project-id @@ -239,12 +241,12 @@ that doesn't exist, {+cli-bin+} can :ref:`create the application The :guilabel:`Project ID` of the :ref:`Atlas project ` on which you want to host a newly created App. If - specified, {+cli-bin+} will not prompt you to select a project when + specified, ``realm-cli`` will not prompt you to select a project when creating a new app. .. note:: - {+cli-bin+} ignores the value of ``--project-id`` + ``realm-cli`` ignores the value of ``--project-id`` unless you are :ref:`importing a new application `. @@ -295,13 +297,13 @@ a local application directory. The path of the directory where App Services will export your application. - If specified, {+cli-bin+} creates a directory at the given path and exports + If specified, ``realm-cli`` creates a directory at the given path and exports the application configuration into the new directory. If a file or directory already exists at the specified path, the export will fail. .. note:: - If the ``output`` argument is omitted, {+cli-bin+} will export the + If the ``output`` argument is omitted, ``realm-cli`` will export the application configuration to a new directory within the current working directory. @@ -316,7 +318,7 @@ a local application directory. | **Optional.** - If enabled, {+cli-bin+} exports the application configuration without any + If enabled, ``realm-cli`` exports the application configuration without any fields that conflict with deployment via GitHub source control, including fields like ``name``, ``app_id``, ``location``, and ``deployment_model`` in the ``config.json`` file as well as the ``config.clusterName`` field in the @@ -326,7 +328,7 @@ a local application directory. | **Optional.** - If enabled, {+cli-bin+} exports the application configuration without any + If enabled, ``realm-cli`` exports the application configuration without any service ID values, including the App ID. This simplifies the creation of new applications from an exported configuration. @@ -659,7 +661,7 @@ match an existing entity, the entity becomes a new entity. If an existing entity's ``name`` does not match the ``name`` of any imported entity, App Services deletes that existing entity. -If an imported entity has no ``name`` value, {+cli-bin+} will throw +If an imported entity has no ``name`` value, ``realm-cli`` will throw an error. .. example:: diff --git a/source/realm-cli/v2.txt b/source/realm-cli/v2.txt new file mode 100644 index 000000000..4512a1dc7 --- /dev/null +++ b/source/realm-cli/v2.txt @@ -0,0 +1,206 @@ +.. _realm-cli: +.. _realm-cli-quickstart: + +============================= +``realm-cli`` v2 [Deprecated] +============================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. include:: /includes/realm-cli-deprecation.rst + +Overview +-------- + +.. program:: realm-cli +.. binary:: realm-cli + +The MongoDB Realm Command Line Interface (``realm-cli``) +allows you to programmatically manage your Apps. +With ``realm-cli``, you can create or update +Apps from a local directory as well as export +existing applications to a local directory. + +.. important:: Check your CLI version + + This page is a quickstart for version 2 of ``realm-cli``. If you need + documentation for version 1 of ``realm-cli``, see: :ref:`Realm CLI v1 `. + To check your CLI version, use: ``realm-cli --version``. + To upgrade your global install to the latest version, use: ``npm upgrade -g mongodb-realm-cli``. + +.. _install-realm-cli: + +Installation +------------ + +.. include:: /includes/install-realm-cli-v2.rst + +.. _realm-cli-auth-with-api-token: + +Authentication +-------------- + +To use ``realm-cli``, you must authenticate. To authenticate, you must generate an +API Key. + +Generate an API Key +~~~~~~~~~~~~~~~~~~~ + +.. procedure:: + + .. step:: Navigate to MongoDB Cloud Access Manager + + The :mms-docs:`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 + :guilabel:`Project Access` tab on the :guilabel:`access manager + dropdown` on your screen's top left-hand side. + + .. figure:: /images/click-access-manager.png + :alt: Click Access Manager + :lightbox: + + + .. step:: Create an API Key + + Project Users can log in using ``realm-cli`` tool with a Project API + Key. Create a project API Key by clicking the grey :guilabel:`Create + API Key` button on the right-hand side of the Project Access Manager. + + .. figure:: /images/access-manager-create-api-key-button.png + :alt: Click Access Manager + :lightbox: + + 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 + :guilabel:`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 :guilabel:`next` to + continue configuring your key details. + + .. figure:: /images/configure-api-key.png + :alt: Click Access Manager + :lightbox: + + + .. step:: 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 :guilabel:`Add Access List Entry` button. + Type in the IP Address or click the :guilabel:`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. + + .. figure:: /images/add-access-list-entry.png + :alt: Click Access Manager + :lightbox: + +Authenticate with an API Key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. procedure:: + + .. step:: Authenticate a CLI User + + Using your newly created public and private key, log in by running the + command below. + + .. code-block:: shell + + realm-cli login --api-key="" --private-api-key="" + + You should see the following result: + + .. code-block:: shell + + you have successfully logged in as + +Options +------- + +Use "realm-cli [command] --help" for information on a specific command + +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - Name + - Type + - Required + - Description + * - --profile + - string + - no + - Specify your profile (Default value: "default") (default "default") + * - --telemetry + - string + - no + - Enable/Disable CLI usage tracking for your current profile (Default value: "on"; Allowed values: "on", "off") + * - -o, --output-target + - string + - no + - Write CLI output to the specified filepath + * - -f, --output-format + - string + - no + - Set the CLI output format (Default value: ; Allowed values: , "json") + * - --disable-colors + - + - no + - Disable all CLI output styling (e.g. colors, font styles, etc.) + * - -y, --yes + - + - no + - Automatically proceed through CLI commands by agreeing to any required user prompts + * - -h, --help + - + - false + - help for realm-cli + +Commands +-------- + +* :ref:`realm-cli-accessList` - Manage allowed IP addresses and CIDR blocks +* :ref:`realm-cli-apps` - Manage the App Services apps associated with the current user (alias: app) +* :ref:`realm-cli-function` - Interact with the Functions of your App (alias: functions) +* :ref:`realm-cli-login` - Log the CLI into App Services using a MongoDB Cloud API key +* :ref:`realm-cli-logout` - Log the CLI out of App Services +* :ref:`realm-cli-logs` - Interact with the Logs of your App (alias: log) +* :ref:`realm-cli-pull` - Exports the latest version of your App into your local directory (alias: export) +* :ref:`realm-cli-push` - Imports and deploys changes from your local directory to your App (alias: import) +* :ref:`realm-cli-schema` - Manage the Schemas of your App (alias: schemas) +* :ref:`realm-cli-secrets` - Manage the Secrets of your App (alias: secret) +* :ref:`realm-cli-users` - Manage the Users of your App (alias: user) +* :ref:`realm-cli-whoami` - Display information about the current user + +.. toctree:: + :titlesonly: + :hidden: + + accessList + apps + function + login + logout + logs + pull + push + schema + secrets + users + whoami diff --git a/source/cli/realm-cli-accessList-create.txt b/source/realm-cli/v2/realm-cli-accessList-create.txt similarity index 97% rename from source/cli/realm-cli-accessList-create.txt rename to source/realm-cli/v2/realm-cli-accessList-create.txt index 91ef263e1..2ab2b1903 100644 --- a/source/cli/realm-cli-accessList-create.txt +++ b/source/realm-cli/v2/realm-cli-accessList-create.txt @@ -4,6 +4,8 @@ realm-cli accessList create =========================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-accessList-delete.txt b/source/realm-cli/v2/realm-cli-accessList-delete.txt similarity index 97% rename from source/cli/realm-cli-accessList-delete.txt rename to source/realm-cli/v2/realm-cli-accessList-delete.txt index ca7f6f5b5..d03f21d41 100644 --- a/source/cli/realm-cli-accessList-delete.txt +++ b/source/realm-cli/v2/realm-cli-accessList-delete.txt @@ -4,6 +4,8 @@ realm-cli accessList delete =========================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-accessList-list.txt b/source/realm-cli/v2/realm-cli-accessList-list.txt similarity index 97% rename from source/cli/realm-cli-accessList-list.txt rename to source/realm-cli/v2/realm-cli-accessList-list.txt index 71e123d0c..2ff1750ae 100644 --- a/source/cli/realm-cli-accessList-list.txt +++ b/source/realm-cli/v2/realm-cli-accessList-list.txt @@ -4,6 +4,8 @@ realm-cli accessList list ========================= +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-accessList-update.txt b/source/realm-cli/v2/realm-cli-accessList-update.txt similarity index 97% rename from source/cli/realm-cli-accessList-update.txt rename to source/realm-cli/v2/realm-cli-accessList-update.txt index e93d842f8..c47932291 100644 --- a/source/cli/realm-cli-accessList-update.txt +++ b/source/realm-cli/v2/realm-cli-accessList-update.txt @@ -4,6 +4,8 @@ realm-cli accessList update =========================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-accessList.txt b/source/realm-cli/v2/realm-cli-accessList.txt similarity index 88% rename from source/cli/realm-cli-accessList.txt rename to source/realm-cli/v2/realm-cli-accessList.txt index 8a4593afb..77632f072 100644 --- a/source/cli/realm-cli-accessList.txt +++ b/source/realm-cli/v2/realm-cli-accessList.txt @@ -4,6 +4,8 @@ realm-cli accessList ==================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page @@ -78,7 +80,7 @@ Related Commands .. toctree:: :titlesonly: - create - delete - list - update + create + delete + list + update diff --git a/source/cli/realm-cli-apps-create.txt b/source/realm-cli/v2/realm-cli-apps-create.txt similarity index 98% rename from source/cli/realm-cli-apps-create.txt rename to source/realm-cli/v2/realm-cli-apps-create.txt index 0e341c206..79aae57f5 100644 --- a/source/cli/realm-cli-apps-create.txt +++ b/source/realm-cli/v2/realm-cli-apps-create.txt @@ -4,6 +4,8 @@ realm-cli apps create ===================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-apps-delete.txt b/source/realm-cli/v2/realm-cli-apps-delete.txt similarity index 97% rename from source/cli/realm-cli-apps-delete.txt rename to source/realm-cli/v2/realm-cli-apps-delete.txt index 2f33059c9..f661d5299 100644 --- a/source/cli/realm-cli-apps-delete.txt +++ b/source/realm-cli/v2/realm-cli-apps-delete.txt @@ -4,6 +4,8 @@ realm-cli apps delete ===================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-apps-describe.txt b/source/realm-cli/v2/realm-cli-apps-describe.txt similarity index 97% rename from source/cli/realm-cli-apps-describe.txt rename to source/realm-cli/v2/realm-cli-apps-describe.txt index 47741c600..143f8f9d1 100644 --- a/source/cli/realm-cli-apps-describe.txt +++ b/source/realm-cli/v2/realm-cli-apps-describe.txt @@ -4,6 +4,8 @@ realm-cli apps describe ======================= +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-apps-diff.txt b/source/realm-cli/v2/realm-cli-apps-diff.txt similarity index 97% rename from source/cli/realm-cli-apps-diff.txt rename to source/realm-cli/v2/realm-cli-apps-diff.txt index 621794ce4..c5fdd66a5 100644 --- a/source/cli/realm-cli-apps-diff.txt +++ b/source/realm-cli/v2/realm-cli-apps-diff.txt @@ -4,6 +4,8 @@ realm-cli apps diff =================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-apps-init.txt b/source/realm-cli/v2/realm-cli-apps-init.txt similarity index 97% rename from source/cli/realm-cli-apps-init.txt rename to source/realm-cli/v2/realm-cli-apps-init.txt index 138c27ca5..b413db889 100644 --- a/source/cli/realm-cli-apps-init.txt +++ b/source/realm-cli/v2/realm-cli-apps-init.txt @@ -4,6 +4,8 @@ realm-cli apps init =================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-apps-list.txt b/source/realm-cli/v2/realm-cli-apps-list.txt similarity index 96% rename from source/cli/realm-cli-apps-list.txt rename to source/realm-cli/v2/realm-cli-apps-list.txt index 8af5f1f7d..dddfe391a 100644 --- a/source/cli/realm-cli-apps-list.txt +++ b/source/realm-cli/v2/realm-cli-apps-list.txt @@ -4,6 +4,8 @@ realm-cli apps list =================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-apps.txt b/source/realm-cli/v2/realm-cli-apps.txt similarity index 85% rename from source/cli/realm-cli-apps.txt rename to source/realm-cli/v2/realm-cli-apps.txt index 72c5c78cf..f87eb0422 100644 --- a/source/cli/realm-cli-apps.txt +++ b/source/realm-cli/v2/realm-cli-apps.txt @@ -4,6 +4,8 @@ realm-cli apps ============== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page @@ -82,9 +84,9 @@ Related Commands .. toctree:: :titlesonly: - create - delete - describe - diff - init - list + create + delete + describe + diff + init + list diff --git a/source/cli/realm-cli-function-run.txt b/source/realm-cli/v2/realm-cli-function-run.txt similarity index 95% rename from source/cli/realm-cli-function-run.txt rename to source/realm-cli/v2/realm-cli-function-run.txt index d404b4b40..972252fc2 100644 --- a/source/cli/realm-cli-function-run.txt +++ b/source/realm-cli/v2/realm-cli-function-run.txt @@ -4,6 +4,8 @@ realm-cli function run ====================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page @@ -51,7 +53,7 @@ Options * - --args - stringArray - false - - Specify the args to pass to your function. Learn more at: :ref:`Call a Function from {+cli+} `. + - Specify the args to pass to your function. Learn more at: :ref:`Call a Function from the CLI `. * - --user - string - false diff --git a/source/cli/realm-cli-function.txt b/source/realm-cli/v2/realm-cli-function.txt similarity index 94% rename from source/cli/realm-cli-function.txt rename to source/realm-cli/v2/realm-cli-function.txt index ab82453ac..72fdd5b32 100644 --- a/source/cli/realm-cli-function.txt +++ b/source/realm-cli/v2/realm-cli-function.txt @@ -4,6 +4,8 @@ realm-cli function ================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page @@ -77,4 +79,4 @@ Related Commands .. toctree:: :titlesonly: - run + run diff --git a/source/cli/realm-cli-login.txt b/source/realm-cli/v2/realm-cli-login.txt similarity index 97% rename from source/cli/realm-cli-login.txt rename to source/realm-cli/v2/realm-cli-login.txt index 31986c26f..24caeac95 100644 --- a/source/cli/realm-cli-login.txt +++ b/source/realm-cli/v2/realm-cli-login.txt @@ -4,6 +4,8 @@ realm-cli login =============== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-logout.txt b/source/realm-cli/v2/realm-cli-logout.txt similarity index 96% rename from source/cli/realm-cli-logout.txt rename to source/realm-cli/v2/realm-cli-logout.txt index 865bfa682..9b2fd6872 100644 --- a/source/cli/realm-cli-logout.txt +++ b/source/realm-cli/v2/realm-cli-logout.txt @@ -4,6 +4,8 @@ realm-cli logout ================ +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-logs-list.txt b/source/realm-cli/v2/realm-cli-logs-list.txt similarity index 93% rename from source/cli/realm-cli-logs-list.txt rename to source/realm-cli/v2/realm-cli-logs-list.txt index 6aadcb405..492d9b982 100644 --- a/source/cli/realm-cli-logs-list.txt +++ b/source/realm-cli/v2/realm-cli-logs-list.txt @@ -4,6 +4,8 @@ realm-cli logs list =================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page @@ -51,11 +53,11 @@ Options * - --start - Date - false - - Specify when to begin listing logs. Learn more at: :ref:` View Logs with {+cli+} `. + - Specify when to begin listing logs. Learn more at: :ref:` View Logs with realm-cli `. * - --end - Date - false - - Specify when to finish listing logs Learn more at: :ref:` View Logs with {+cli+} `. + - Specify when to finish listing logs Learn more at: :ref:` View Logs with realm-cli `. * - --tail - - false diff --git a/source/cli/realm-cli-logs.txt b/source/realm-cli/v2/realm-cli-logs.txt similarity index 94% rename from source/cli/realm-cli-logs.txt rename to source/realm-cli/v2/realm-cli-logs.txt index 64825ba6b..aa754c96f 100644 --- a/source/cli/realm-cli-logs.txt +++ b/source/realm-cli/v2/realm-cli-logs.txt @@ -4,6 +4,8 @@ realm-cli logs ============== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page @@ -77,4 +79,4 @@ Related Commands .. toctree:: :titlesonly: - list + list diff --git a/source/cli/realm-cli-pull.txt b/source/realm-cli/v2/realm-cli-pull.txt similarity index 98% rename from source/cli/realm-cli-pull.txt rename to source/realm-cli/v2/realm-cli-pull.txt index 2fd1231b5..435d5b86f 100644 --- a/source/cli/realm-cli-pull.txt +++ b/source/realm-cli/v2/realm-cli-pull.txt @@ -4,6 +4,8 @@ realm-cli pull ============== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-push.txt b/source/realm-cli/v2/realm-cli-push.txt similarity index 98% rename from source/cli/realm-cli-push.txt rename to source/realm-cli/v2/realm-cli-push.txt index c0eb58a1d..66dc7c033 100644 --- a/source/cli/realm-cli-push.txt +++ b/source/realm-cli/v2/realm-cli-push.txt @@ -4,6 +4,8 @@ realm-cli push ============== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-schema-datamodels.txt b/source/realm-cli/v2/realm-cli-schema-datamodels.txt similarity index 98% rename from source/cli/realm-cli-schema-datamodels.txt rename to source/realm-cli/v2/realm-cli-schema-datamodels.txt index f5c015d3f..eb6d54fb1 100644 --- a/source/cli/realm-cli-schema-datamodels.txt +++ b/source/realm-cli/v2/realm-cli-schema-datamodels.txt @@ -4,6 +4,8 @@ realm-cli schema datamodels =========================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-schema.txt b/source/realm-cli/v2/realm-cli-schema.txt similarity index 93% rename from source/cli/realm-cli-schema.txt rename to source/realm-cli/v2/realm-cli-schema.txt index c29105ffd..57e4301a0 100644 --- a/source/cli/realm-cli-schema.txt +++ b/source/realm-cli/v2/realm-cli-schema.txt @@ -4,6 +4,8 @@ realm-cli schema ================ +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page @@ -77,4 +79,4 @@ Related Commands .. toctree:: :titlesonly: - datamodels + datamodels diff --git a/source/cli/realm-cli-secrets-create.txt b/source/realm-cli/v2/realm-cli-secrets-create.txt similarity index 97% rename from source/cli/realm-cli-secrets-create.txt rename to source/realm-cli/v2/realm-cli-secrets-create.txt index 62108a652..16b1dd8c1 100644 --- a/source/cli/realm-cli-secrets-create.txt +++ b/source/realm-cli/v2/realm-cli-secrets-create.txt @@ -4,6 +4,8 @@ realm-cli secrets create ======================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-secrets-delete.txt b/source/realm-cli/v2/realm-cli-secrets-delete.txt similarity index 97% rename from source/cli/realm-cli-secrets-delete.txt rename to source/realm-cli/v2/realm-cli-secrets-delete.txt index 6de1ab95c..79673098f 100644 --- a/source/cli/realm-cli-secrets-delete.txt +++ b/source/realm-cli/v2/realm-cli-secrets-delete.txt @@ -4,6 +4,8 @@ realm-cli secrets delete ======================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-secrets-list.txt b/source/realm-cli/v2/realm-cli-secrets-list.txt similarity index 97% rename from source/cli/realm-cli-secrets-list.txt rename to source/realm-cli/v2/realm-cli-secrets-list.txt index 1ff8f12f0..d52419245 100644 --- a/source/cli/realm-cli-secrets-list.txt +++ b/source/realm-cli/v2/realm-cli-secrets-list.txt @@ -4,6 +4,8 @@ realm-cli secrets list ====================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-secrets-update.txt b/source/realm-cli/v2/realm-cli-secrets-update.txt similarity index 97% rename from source/cli/realm-cli-secrets-update.txt rename to source/realm-cli/v2/realm-cli-secrets-update.txt index 1814d1906..e5c019673 100644 --- a/source/cli/realm-cli-secrets-update.txt +++ b/source/realm-cli/v2/realm-cli-secrets-update.txt @@ -4,6 +4,8 @@ realm-cli secrets update ======================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-secrets.txt b/source/realm-cli/v2/realm-cli-secrets.txt similarity index 87% rename from source/cli/realm-cli-secrets.txt rename to source/realm-cli/v2/realm-cli-secrets.txt index e2ed94edb..0de57cf9e 100644 --- a/source/cli/realm-cli-secrets.txt +++ b/source/realm-cli/v2/realm-cli-secrets.txt @@ -4,6 +4,8 @@ realm-cli secrets ================= +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page @@ -80,7 +82,7 @@ Related Commands .. toctree:: :titlesonly: - create - delete - list - update + create + delete + list + update diff --git a/source/cli/realm-cli-users-create.txt b/source/realm-cli/v2/realm-cli-users-create.txt similarity index 97% rename from source/cli/realm-cli-users-create.txt rename to source/realm-cli/v2/realm-cli-users-create.txt index 9fe503b28..d75f72b47 100644 --- a/source/cli/realm-cli-users-create.txt +++ b/source/realm-cli/v2/realm-cli-users-create.txt @@ -4,6 +4,8 @@ realm-cli users create ====================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-users-delete.txt b/source/realm-cli/v2/realm-cli-users-delete.txt similarity index 97% rename from source/cli/realm-cli-users-delete.txt rename to source/realm-cli/v2/realm-cli-users-delete.txt index 18d6667fe..a674fc485 100644 --- a/source/cli/realm-cli-users-delete.txt +++ b/source/realm-cli/v2/realm-cli-users-delete.txt @@ -4,6 +4,8 @@ realm-cli users delete ====================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-users-disable.txt b/source/realm-cli/v2/realm-cli-users-disable.txt similarity index 97% rename from source/cli/realm-cli-users-disable.txt rename to source/realm-cli/v2/realm-cli-users-disable.txt index 7ba4021bf..bd166dae7 100644 --- a/source/cli/realm-cli-users-disable.txt +++ b/source/realm-cli/v2/realm-cli-users-disable.txt @@ -4,6 +4,8 @@ realm-cli users disable ======================= +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-users-enable.txt b/source/realm-cli/v2/realm-cli-users-enable.txt similarity index 97% rename from source/cli/realm-cli-users-enable.txt rename to source/realm-cli/v2/realm-cli-users-enable.txt index e8bae38a8..b5c776322 100644 --- a/source/cli/realm-cli-users-enable.txt +++ b/source/realm-cli/v2/realm-cli-users-enable.txt @@ -4,6 +4,8 @@ realm-cli users enable ====================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-users-list.txt b/source/realm-cli/v2/realm-cli-users-list.txt similarity index 97% rename from source/cli/realm-cli-users-list.txt rename to source/realm-cli/v2/realm-cli-users-list.txt index e72c5d920..1d5410803 100644 --- a/source/cli/realm-cli-users-list.txt +++ b/source/realm-cli/v2/realm-cli-users-list.txt @@ -4,6 +4,8 @@ realm-cli users list ==================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-users-revoke.txt b/source/realm-cli/v2/realm-cli-users-revoke.txt similarity index 97% rename from source/cli/realm-cli-users-revoke.txt rename to source/realm-cli/v2/realm-cli-users-revoke.txt index 0f275b18a..832c70ece 100644 --- a/source/cli/realm-cli-users-revoke.txt +++ b/source/realm-cli/v2/realm-cli-users-revoke.txt @@ -4,6 +4,8 @@ realm-cli users revoke ====================== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/cli/realm-cli-users.txt b/source/realm-cli/v2/realm-cli-users.txt similarity index 84% rename from source/cli/realm-cli-users.txt rename to source/realm-cli/v2/realm-cli-users.txt index abc69b1e9..643332741 100644 --- a/source/cli/realm-cli-users.txt +++ b/source/realm-cli/v2/realm-cli-users.txt @@ -4,6 +4,8 @@ realm-cli users =============== +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page @@ -82,9 +84,9 @@ Related Commands .. toctree:: :titlesonly: - create - delete - disable - enable - list - revoke + create + delete + disable + enable + list + revoke diff --git a/source/cli/realm-cli-whoami.txt b/source/realm-cli/v2/realm-cli-whoami.txt similarity index 97% rename from source/cli/realm-cli-whoami.txt rename to source/realm-cli/v2/realm-cli-whoami.txt index 1175f7842..095c09e43 100644 --- a/source/cli/realm-cli-whoami.txt +++ b/source/realm-cli/v2/realm-cli-whoami.txt @@ -4,6 +4,8 @@ realm-cli whoami ================ +.. include:: /includes/realm-cli-deprecation.rst + .. default-domain:: mongodb .. contents:: On this page diff --git a/source/reference.txt b/source/reference.txt index 05aee201f..a6ee1d5bb 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -15,6 +15,7 @@ Reference Template Apps Third-Party Licenses Upgrade a Shared Tier Cluster + Realm CLI [Deprecated] Partition-Based Sync Mode Push Notifications [Deprecated] Third-Party Services [Deprecated] diff --git a/source/reference/config.txt b/source/reference/config.txt index b590fbaed..dd1470994 100644 --- a/source/reference/config.txt +++ b/source/reference/config.txt @@ -19,14 +19,14 @@ App Configuration Functions GraphQL Static Hosting - HTTP Endpoints + HTTPS Endpoints Log Forwarders - Third-Party Services Atlas Device Sync Triggers Values Create Template Configurations with Expansions - Legacy Configuration Files + v20210101 [Deprecated] + v20180301 [Deprecated] Every component of an Atlas App Services App is fully defined and configured using structured JSON configuration and JavaScript source code files. @@ -58,16 +58,15 @@ and directories: .. code-block:: none app/ - ├── realm_config.json + ├── root_config.json ├── auth/ ├── data_sources/ ├── environments/ ├── functions/ ├── graphql/ ├── hosting/ - ├── http_endpoints/ + ├── https_endpoints/ ├── log_forwarders/ - ├── services/ ├── sync/ ├── triggers/ └── values/ @@ -82,9 +81,8 @@ and source code files, refer to the type's page in this section: - :doc:`Functions ` - :doc:`GraphQL ` - :doc:`Static Hosting ` -- :doc:`HTTP Endpoints ` +- :doc:`HTTPS Endpoints ` - :doc:`Log Forwarders ` -- :doc:`Third-Party Services ` - :doc:`Atlas Device Sync ` - :doc:`Triggers ` - :doc:`Values ` diff --git a/source/reference/config/app.txt b/source/reference/config/app.txt index 471bb19c7..bcb66fcef 100644 --- a/source/reference/config/app.txt +++ b/source/reference/config/app.txt @@ -12,28 +12,34 @@ App Configuration Files :depth: 2 :class: singlecol -You can configure high-level features of your application in -``realm_config.json``. +You configure Application-level settings like your App name, +environment, and deployment configuration in ``root_config.json``. .. code-block:: none app/ - └── realm_config.json + └── root_config.json -Configuration -------------- +.. tip:: -.. code-block:: javascript - :caption: /realm_config.json + If you're using the {+cli+}, you can find metadata information about + your specific deployed App instance in :ref:`the .mdb directory `. + +Root Configuration +------------------ + +Your configuration directory must include a ``root_config.json`` file +with the following structure: + +.. code-block:: typescript + :caption: /root_config.json { - "app_id": "", "name": "", - "config_version": , - "environment": "", - "allowed_request_origins": ["", ...], "deployment_model": "", - "location": "" + "provider_region": "", + "environment": "", + "allowed_request_origins": ["", ...] } .. list-table:: @@ -42,67 +48,67 @@ Configuration * - Field - Description - - * - | ``app_id`` - | String - - The application's :guilabel:`App ID`. - + * - | ``name`` - | String + | ``string`` + - The application's name. - + .. include:: /includes/note-app-name-limitations.rst - - * - | ``config_version`` - | Number - - - The schema version that all configuration files in the application - conform to. This value is machine generated and you typically should not - manually set or modify it. - + + * - | ``deployment_model`` + | ``string`` + + - The application's :ref:`deployment model `. + + Valid options: + + - ``"GLOBAL"`` for :ref:`Global Deployment ` + - ``"LOCAL"`` for :ref:`Local Deployment ` + + * - | ``provider_region`` + | ``string`` + + - The name of the :ref:`cloud region ` that the + application is deployed in. + + - :ref:`Global applications ` process + all database writes in this region, but serve other application + requests in the nearest deployment region. + + - :ref:`Local applications ` process all + application requests and database writes in this region. + * - | ``environment`` - | String - - - The name of the environment the app should - use when evaluating :ref:`environment values `. - + | ``string?`` + + - The name of the environment the app should use when evaluating + :ref:`environment values `. + Valid options: - + .. include:: /includes/list-of-environment-names.rst Default: ``""`` - + * - | ``allowed_request_origins`` - | Document + | ``string[]?`` + - An array of URLs that incoming requests may originate from. If you define any allowed request origins, then Atlas App Services blocks any incoming request from an origin that is not listed. - + .. tip:: - + Request origins are URLs with the following form: - + .. code-block:: text - + ://[:port] - - * - | ``deployment_model`` - | String - - The application's :ref:`deployment model `. - - Valid options: - - - ``"GLOBAL"`` for :ref:`Global Deployment ` - - ``"LOCAL"`` for :ref:`Local Deployment ` - - * - | ``location`` - | String - - The name of the :ref:`cloud region ` that the application - is deployed in. - - - :ref:`Global applications ` process - all database writes in this region, but serve other application - requests in the nearest deployment region. - - - :ref:`Local applications ` process all - application requests and database writes in this region. + + For example, the following are both valid request origins: + + .. code-block:: text + + https://www.example.com + https://www.example.com:443 diff --git a/source/reference/config/auth.txt b/source/reference/config/auth.txt index 497b701b3..e99b842a5 100644 --- a/source/reference/config/auth.txt +++ b/source/reference/config/auth.txt @@ -75,12 +75,12 @@ configuration fields. - Description * - | ``name`` - | String + | ``string`` - The name of the authentication provider. This will always be the same as the the provider's ``type``. * - | ``type`` - | String + | ``string`` - The authentication provider type. Valid options: @@ -185,24 +185,24 @@ collection for your app in ``/auth/custom_user_data.json``. collection that contains their custom data. * - | ``mongo_service_name`` - | String + | ``string`` - The name of the :ref:`data source ` that contains the custom user data collection. * - | ``database_name`` - | String + | ``string`` - The name of the database that contains the custom user data collection. * - | ``collection_name`` - | String + | ``string`` - The name of the collection that contains the custom user data. * - | ``user_id_field`` - | String + | ``string`` - The name of the field in custom user data documents that contains the user ID of the application user the document describes. * - | ``on_user_creation_function_name`` - | String + | ``string?`` - The name of the :ref:`user creation function `. diff --git a/source/reference/config/data_sources.txt b/source/reference/config/data_sources.txt index 923a1bd0f..2e407a0db 100644 --- a/source/reference/config/data_sources.txt +++ b/source/reference/config/data_sources.txt @@ -53,7 +53,7 @@ MongoDB Clusters - Description * - | ``name`` - | String + | ``string`` - Required. Default: ``mongodb-atlas`` The service name used to refer to the cluster within this Atlas App Services @@ -61,15 +61,15 @@ MongoDB Clusters contain ASCII letters, numbers, underscores, and hyphens. * - | ``type`` - | String + | ``string`` - Required. For MongoDB Atlas clusters, this value is always ``"mongodb-atlas"``. * - | ``config.clusterName`` - | String + | ``string`` - Required. The name of the cluster in Atlas. * - | ``config.readPreference`` - | String + | ``string`` - The :ref:`read preference ` mode for queries sent through the service. @@ -104,7 +104,7 @@ MongoDB Clusters - Description * - | ``name`` - | String + | ``string`` - Required. Default: ``mongodb-datafederation`` The service name used to refer to the {+adf-instance+} within this App Services @@ -112,11 +112,11 @@ MongoDB Clusters contain ASCII letters, numbers, underscores, and hyphens. * - | ``type`` - | String + | ``string`` - Required. For a {+adf-instance+}, this value is always ``"datalake"``. * - | ``config.dataLakeName`` - | String + | ``string`` - Required. The name of the {+adf-instance+} in Atlas. Databases & Collections @@ -170,7 +170,7 @@ Relationships - Description * - | ``ref`` - | String + | ``string`` - A JSON schema ``$ref`` string that specifies the foreign collection. The string has the following form: @@ -179,14 +179,14 @@ Relationships #/relationship/// * - | ``source_key`` - | String + | ``string`` - The name of the field in this collection's schema that specifies which documents in the foreign collection to include in the relationship. A foreign document is included if ``source_key`` contains the value of its ``foreign_key`` field. * - | ``foreign_key`` - | String + | ``string`` - The name of the field in the foreign collection's schema that contains the value referenced by ``source_key``. @@ -251,11 +251,11 @@ configuration file at ``data_sources//default_rule.json``. * - | ``roles`` | Array - - An array of :ref:`Role ` configurations. + - An array of :ref:`Role ` configurations. * - | ``filters`` | Array - - An array of :ref:`Filter ` configurations. + - An array of :ref:`Filter ` configurations. .. _config-collection-rules: @@ -284,27 +284,27 @@ configuration file. - Description * - | ``database`` - | String + | ``string`` - The name of the database that holds the collection. * - | ``collection`` - | String + | ``string`` - The name of the collection. * - | ``roles`` - | Array - - An array of :ref:`Role ` configurations. + | ``Role[]`` + - An array of :ref:`Role ` configurations. * - | ``filters`` - | Array - - An array of :ref:`Filter ` configurations. + | ``Filter[]`` + - An array of :ref:`Filter ` configurations. -.. _rule-config: +.. _config-rule: Rule Configurations ------------------- -.. _role-config: +.. _config-role: Roles ~~~~~ @@ -312,7 +312,7 @@ Roles .. include:: /mongodb/tables/role-configuration.rst -.. _filter-config: +.. _config-filter: Filters ~~~~~~~ diff --git a/source/reference/config/environments.txt b/source/reference/config/environments.txt index 30e889e09..1f75ff88e 100644 --- a/source/reference/config/environments.txt +++ b/source/reference/config/environments.txt @@ -50,6 +50,6 @@ Atlas App Services supports the following environments: - Description * - | ``values`` - | Object + | ``object`` - An object where each property maps the name of an environment value name to its value in the current environment. diff --git a/source/reference/config/functions.txt b/source/reference/config/functions.txt index 7f8bd854b..7589365a1 100644 --- a/source/reference/config/functions.txt +++ b/source/reference/config/functions.txt @@ -57,42 +57,42 @@ in the function manifest file: ``/functions/config.json``. - Description * - | ``name`` - | String + | ``string`` - The name of the function. The name must match the file name of a :ref:`source code file ` and be unique among all functions in your application. * - | ``private`` - | Boolean + | ``boolean`` - If ``true``, this function may only be called from other functions or in :json-operator:`%function` rule expressions. You cannot call a private function directly from a client application or with an SDK. * - | ``can_evaluate`` - | JSON Expression (default: ``true``) + | ``object`` - A :ref:`JSON expression ` that evaluates to ``true`` if the function is allowed to execute. App Services evaluates this expression for every incoming request. * - | ``disable_arg_logs`` - | Boolean + | ``boolean`` - If ``true``, App Services omits the arguments provided to the function from the :ref:`function execution log entry `. * - | ``run_as_system`` - | Boolean + | ``boolean`` - If ``true``, this function :ref:`runs as the system user `. This overrides any values defined for ``run_as_user_id`` and ``run_as_user_id_script_source``. * - | ``run_as_user_id`` - | String + | ``string`` - The unique ID of a :doc:`App Services User ` that the function always executes as. Cannot be used with ``run_as_user_id_script_source``. * - | ``run_as_user_id_script_source`` - | String + | ``string`` - A stringified :doc:`function ` that runs whenever the function is called and returns the unique ID of a :doc:`App Services User ` that the function executes as. Cannot be used with diff --git a/source/reference/config/graphql.txt b/source/reference/config/graphql.txt index 78713691f..7e89e8983 100644 --- a/source/reference/config/graphql.txt +++ b/source/reference/config/graphql.txt @@ -42,7 +42,7 @@ Service Configuration - Description * - | ``use_natural_pluralization`` - | Boolean + | ``boolean`` - ``true`` by default for new apps. You can only set the value to ``false`` when you :admin-api-endpoint:`create a new app with the Admin API endpoint ` @@ -65,7 +65,7 @@ Service Configuration - Default: "mouses" * - | ``disable_schema_introspection`` - | Boolean + | ``boolean`` - This value is ``false`` by default for new apps. If ``true``, the GraphQL API blocks :graphql:`introspection @@ -102,7 +102,7 @@ Custom Resolver Configuration - Description * - | ``on_type`` - | String + | ``string`` - The parent type that exposes the custom resolver as one of its fields. Valid Options: @@ -112,7 +112,7 @@ Custom Resolver Configuration - A singular :ref:`exposed ` type name (for :ref:`computed properties `) * - | ``field_name`` - | String + | ``string`` - The name of the field on the parent type that exposes the custom resolver. The field name must be unique among all custom resolver on its parent type. @@ -121,7 +121,7 @@ Custom Resolver Configuration resolver overrides the schema type. * - | ``function_name`` - | String + | ``string`` - The name of the :ref:`function ` that runs when the resolver is called. The function arguments may accept a single argument (configured by ``input_type`` and ``input_type_format``) and must return @@ -129,13 +129,13 @@ Custom Resolver Configuration ``payload_type_format``). * - | ``input_type`` - | String | JSON Schema + | ``string | object`` - The type of the resolver's ``input`` argument (if it accepts input). You can specify either the name of another type in your GraphQL schema or a custom JSON schema specific to the resolver. * - | ``input_type_format`` - | String + | ``string`` - A metadata description of the ``input_type``. Valid Options: @@ -147,7 +147,7 @@ Custom Resolver Configuration - ``"custom"`` (for a custom JSON schema) * - | ``payload_type`` - | String | JSON Schema + | ``string | object`` - The type of the value returned in the resolver's payload. You can specify either the name of another type in your GraphQL schema or a custom JSON schema specific to the resolver. @@ -159,7 +159,7 @@ Custom Resolver Configuration :language: graphql * - | ``payload_type_format`` - | String + | ``string`` - A metadata description of the ``payload_type``. Valid Options: diff --git a/source/reference/config/hosting.txt b/source/reference/config/hosting.txt index 949247672..3b622d112 100644 --- a/source/reference/config/hosting.txt +++ b/source/reference/config/hosting.txt @@ -44,16 +44,16 @@ application in ``hosting/config.json``. - Description * - | ``enabled`` - | Boolean + | ``boolean`` - If ``true``, :doc:`static hosting ` is enabled for your app. * - | ``custom_domain`` - | String + | ``string`` - The :doc:`custom domain name ` for your application's hosted files. * - | ``app_default_domain`` - | String + | ``string`` - The default domain for your application's hosted files. Atlas App Services automatically sets this value and you cannot change it. @@ -88,11 +88,11 @@ You can define metadata for any hosted file by adding an entry to - Description * - | ``path`` - | String + | ``string`` - The :ref:`resource path ` of the file. * - | ``attrs`` - | Array + | ``object[]`` - An array of documents where each document represents a single metadata attribute. Attribute documents have the following form: @@ -112,13 +112,13 @@ You can define metadata for any hosted file by adding an entry to - Description * - | ``name`` - | String + | ``string`` - The name of the metadata attribute. This should be one of the :doc:`file metadata attributes ` that App Services supports. * - | ``value`` - | String + | ``string`` - The value of the metadata attribute. .. include:: /hosting/includes/note-infer-content-type.rst diff --git a/source/reference/config/https_endpoints.txt b/source/reference/config/https_endpoints.txt new file mode 100644 index 000000000..2033802e9 --- /dev/null +++ b/source/reference/config/https_endpoints.txt @@ -0,0 +1,220 @@ +.. _appconfig-https_endpoints: + +================================== +HTTPS Endpoint Configuration Files +================================== + +.. default-domain:: mongodb + +.. code-block:: none + + app/ + └── https_endpoints/ + ├── config.json + └── data_api_config.json + +.. _appconfig-endpoints: + +Custom HTTPS Endpoint Configuration +----------------------------------- + +Define the configurations for all of your app's :ref:`custom HTTPS +endpoints ` as an array in ``https_endpoints/config.json``. + +.. code-block:: json + + [ + { + "route": "", + "http_method": "", + "function_name": "", + "secret_name": "", + "respond_result": , + "fetch_custom_user_data": , + "create_user_on_auth": , + "disabled": + } + ] + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``route`` + | ``string`` + + - The endpoint :ref:`route `. + + * - | ``http_method`` + | ``string`` + + - The type of :mdn:`HTTP method ` that the + endpoint handles. Specify ``*`` to handle all methods with a + single endpoint. + + One of: + + - ``"GET"`` + - ``"POST"`` + - ``"PUT"`` + - ``"PATCH"`` + - ``"DELETE"`` + - ``"DELETE"`` + - ``"*"`` + + * - | ``function_name`` + | ``string`` + + - The name of the :ref:`function ` associated + with the endpoint. The function should use the :ref:`endpoint + function signature `. + + * - | ``validation_method`` + | ``string`` + + - The :ref:`endpoint authorization scheme ` + used to validate incoming requests. + + One of: + + - ``"SECRET_AS_QUERY_PARAM"`` + - ``"VERIFY_PAYLOAD"`` + - ``"NO_VALIDATION"`` + + * - | ``secret_name`` + | ``string`` + + - The name of a :ref:`secret ` that contains a string. + If ``validation_method`` is set to ``SECRET_AS_QUERY_PARAM`` or + ``VERIFY_PAYLOAD``, this secret is used to authorize requests. + + * - | ``respond_result`` + | ``boolean`` + + - If ``true``, the endpoint returns a customizable HTTP response to + the client. You configure the response by calling the methods on + the :ref:`Response ` object. If you do + not configure the response, the endpoint returns a ``200 - Ok`` + response with the value returned from the endpont function as the + request body. + + If ``false``, requests return a ``204 - No Content`` response + with no data in the body. + + * - | ``fetch_custom_user_data`` + | ``boolean`` + + - If ``true``, the authenticated user's :ref:`custom user data + ` document is available via + ``context.user.custom_data``. + + If ``false``, the user's custom data is not queried and + ``context.user.custom_data`` is an empty object. + + * - | ``create_user_on_auth`` + | ``boolean`` + + - If ``true``, your app automatically creates a new user + if the provided user credentials authenticate successfully but + aren't associated with an existing user. + + This setting is useful for apps that integrate with external + authentication system through the Custom JWT authentication + provider. If a request includes a valid JWT from the external system + that doesn't correspond to a registered user, this creates a new + user with the JWT as an identity. + + * - | ``disabled`` + | ``boolean`` + + - Enables (``false``) or disables (``true``) the endpoint. + +.. _appconfig-data-api-endpoints: + +Data API Configuration +---------------------- + +Define the configuration for your app's generated :ref:`Data API +endpoints ` in ``https_endpoints/data_api_config.json``. + +.. code-block:: json + + { + "disabled": , + "versions": ["v1"], + "return_type": "EJSON" | "JSON", + "create_user_on_auth": , + "run_as_system": , + "run_as_user_id": "", + "run_as_user_id_script_source": "" + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``disabled`` + | ``boolean`` + + - If ``false``, the Data API is not enabled. Generated endpoints + will not handle or respond to requests. + + * - | ``versions`` + | ``string[]`` + + - A list of Data API versions that your app supports. The list may + include a subset of all possible versions but must list the + versions in ascending order. You cannot enable a version other + than the most recent version but any previously enabled versions + listed here will continue to work. + + Available Versions: + + - ``"v1"`` + + * - | ``return_type`` + | ``string`` + + - The data format to use for data returned by endpoints in HTTPS + response bodies. + + One of: + + - ``"EJSON"`` + - ``"JSON"`` + + * - | ``create_user_on_auth`` + | ``boolean`` + + - If ``true``, your app automatically creates a new user + if the provided user credentials authenticate successfully but + aren't associated with an existing user. + + This setting is useful for apps that integrate with external + authentication system through the Custom JWT authentication + provider. If a request includes a valid JWT from the external system + that doesn't correspond to a registered user, this creates a new + user with the JWT as an identity. + + * - | ``run_as_user_id`` + | ``string`` + - An application user's account ID. If defined, endpoints will + always run as the specified user. + + Cannot be used with ``run_as_user_id_script_source``. + + * - | ``run_as_user_id_script_source`` + | ``string`` + - Stringified source code for a :ref:`function ` that + returns an application user's account ID. If defined, endpoints + execute the function on every request and run as the user with + the ID returned from the function. + + Cannot be used with ``run_as_user_id``. diff --git a/source/reference/config/legacy.txt b/source/reference/config/legacy.txt index 24756bf9f..f66c80a0e 100644 --- a/source/reference/config/legacy.txt +++ b/source/reference/config/legacy.txt @@ -4,8 +4,8 @@ Application Configuration Files (Legacy) .. note:: Legacy Page - This page describes an older configuration file format still used by some - existing applications. For an up-to-date description of Atlas App Services + This page describes the legacy configuration file format used by + ``realm-cli`` version 1. For an up-to-date description of Atlas App Services configuration files, see :ref:`App Configuration `. diff --git a/source/reference/config/log_forwarders.txt b/source/reference/config/log_forwarders.txt index 6e87c3e14..be0f17b3c 100644 --- a/source/reference/config/log_forwarders.txt +++ b/source/reference/config/log_forwarders.txt @@ -34,11 +34,11 @@ directory. - Description * - | ``name`` - | String + | ``string`` - A unique name for the log forwarder. * - | ``log_types`` - | Array + | ``string[]`` - An array of one or more log types that the forwarder should send to a service. Atlas App Services only forwards a log if its type is listed *and* its status is listed in ``log_statuses``. @@ -48,7 +48,7 @@ directory. .. include:: /includes/log-forwarder-types.rst * - | ``log_statuses`` - | Array + | ``string[]`` - An array of one or more log statuses that the forwarder should send to a service. App Services only forwards a log if its type is listed *and* its type is listed in ``log_types``. @@ -58,7 +58,7 @@ directory. .. include:: /includes/log-forwarder-statuses.rst * - | ``policy`` - | Object + | ``object`` - An object that configures the forwarder's batching policy. To forward logs individually: @@ -74,7 +74,7 @@ directory. { "type": "batch" } * - | ``action`` - | Object + | ``object`` - An object that configures where and how the forwarder sends logs. To forward logs to a linked MongoDB collection: diff --git a/source/reference/config/sync.txt b/source/reference/config/sync.txt index 06704d027..a6c70b49a 100644 --- a/source/reference/config/sync.txt +++ b/source/reference/config/sync.txt @@ -19,4 +19,7 @@ directory: └── sync/ └── config.json -Refer to :ref:`appconfig-sync` for details. +Sync Configuration +------------------ + +.. include:: /sync/config-table.rst diff --git a/source/reference/config/template-expansions.txt b/source/reference/config/template-expansions.txt index 3c8b38795..9cc3bc11d 100644 --- a/source/reference/config/template-expansions.txt +++ b/source/reference/config/template-expansions.txt @@ -158,7 +158,7 @@ Define a Template .. code-block:: shell - realm-cli push + {+cli-bin+} push .. code-block:: json :caption: data_sources/mongodb-atlas/config.json diff --git a/source/reference/config/triggers.txt b/source/reference/config/triggers.txt index 4e72d54bc..3e926022f 100644 --- a/source/reference/config/triggers.txt +++ b/source/reference/config/triggers.txt @@ -45,13 +45,13 @@ trigger type. The following fields exist in *all* trigger configuration files: - Description * - | ``name`` - | String + | ``string`` - The trigger name. This may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens. * - | ``type`` - | String + | ``string`` - The trigger type. The value of this field determines the exact configuration file schema. @@ -62,7 +62,7 @@ trigger type. The following fields exist in *all* trigger configuration files: - ``"SCHEDULED"`` * - | ``config`` - | Document + | ``object`` - A document with fields that map to additional configuration options for the trigger. The exact configuration fields depend on the trigger ``type``: @@ -72,12 +72,12 @@ trigger type. The following fields exist in *all* trigger configuration files: - :ref:`Scheduled Triggers ` * - | ``function_name`` - | String + | ``string`` - The name of the :ref:`Atlas Function ` that the trigger executes whenever it fires. * - | ``event_processors`` - | Document + | ``object`` - A document that configures the trigger to send events to external event processors whenever it fires. Cannot be used with ``function_name``. @@ -85,7 +85,7 @@ trigger type. The following fields exist in *all* trigger configuration files: `. * - | ``disabled`` - | Boolean + | ``boolean`` - If ``true``, the trigger will not listen for any events and will not fire. @@ -129,7 +129,7 @@ configuration files: - Description * - | ``config.service_name`` - | String + | ``string`` - The name of the :ref:`MongoDB data source ` that contains the watched collection. You cannot define a database @@ -137,15 +137,15 @@ configuration files: :ref:`{+adf-instance+} `. * - | ``config.database`` - | String + | ``string`` - The name of the MongoDB database that contains the watched collection. * - | ``config.collection`` - | String + | ``string`` - The name of the collection that the trigger watches. * - | ``config.operation_types`` - | String[] + | ``string[]`` - A list of one or more :ref:`database operation types ` that cause the trigger to fire. @@ -164,7 +164,7 @@ configuration files: rather than ``UPDATE`` events. * - | ``config.full_document`` - | Boolean + | ``boolean`` - If ``true``, ``UPDATE`` change events include the latest :manual:`majority-committed ` version of the modified document *after* the change was applied in the @@ -180,7 +180,7 @@ configuration files: - ``DELETE`` events never include the ``fullDocument`` field. * - | ``config.full_document_before_change`` - | Boolean + | ``boolean`` - If ``true``, change events include a copy of the modified document from immediately *before* the change was applied in the ``fullDocumentBeforeChange`` field. All change events except for @@ -205,7 +205,7 @@ configuration files: For more information, see :ref:`preimages`. * - | ``config.tolerate_resume_errors`` - | Boolean + | ``boolean`` - If ``true``, the Trigger automatically resumes if the token required to process change stream events cannot be found. @@ -215,17 +215,17 @@ configuration files: :ref:`Suspended Triggers `. * - | ``config.unordered`` - | Boolean + | ``boolean`` - If ``true``, indicates that event ordering is disabled for this trigger. .. include:: /includes/trigger-event-ordering.rst * - | ``config.match`` - | Document + | ``object`` - .. include:: /includes/trigger-match-expression.rst * - | ``config.project`` - | Document + | ``object`` - .. include:: /includes/trigger-project-expression.rst .. _config-authentication-trigger: @@ -260,7 +260,7 @@ configuration files: - Description * - | ``config.operation_type`` - | String + | ``string`` - The :ref:`authentication operation type ` that causes the trigger to fire. @@ -271,7 +271,7 @@ configuration files: - ``"DELETE"`` * - | ``config.providers`` - | String[] + | ``string[]`` - A list of :ref:`authentication provider ` types that the trigger watches. @@ -309,6 +309,6 @@ fires. The following fields exist in *scheduled* trigger configuration files: - Description * - | ``config.schedule`` - | String + | ``string`` - The :ref:`CRON expression ` that schedules the trigger's execution. diff --git a/source/reference/config/v20210101.txt b/source/reference/config/v20210101.txt new file mode 100644 index 000000000..5b6b157f2 --- /dev/null +++ b/source/reference/config/v20210101.txt @@ -0,0 +1,40 @@ +======================================================== +Application Configuration Files (v20210101) [Deprecated] +======================================================== + +.. include:: /reference/config/v20210101/note-old-version.rst + + +.. code-block:: none + + app/ + ├── realm_config.json + ├── auth/ + ├── data_sources/ + ├── environments/ + ├── functions/ + ├── graphql/ + ├── hosting/ + ├── http_endpoints/ + ├── log_forwarders/ + ├── services/ + ├── sync/ + ├── triggers/ + └── values/ + +For detailed descriptions and examples of each component type's configuration +and source code files, refer to the type's page in this section: + +- :doc:`App Services App ` +- :doc:`Users & Authentication Providers ` +- :doc:`MongoDB Data Sources ` +- :doc:`Environment Values ` +- :doc:`Functions ` +- :doc:`GraphQL ` +- :doc:`Static Hosting ` +- :doc:`HTTP Endpoints ` +- :doc:`Log Forwarders ` +- :doc:`Third-Party Services ` +- :doc:`Atlas Device Sync ` +- :doc:`Triggers ` +- :doc:`Values ` diff --git a/source/reference/config/v20210101/app.txt b/source/reference/config/v20210101/app.txt new file mode 100644 index 000000000..0918af8cb --- /dev/null +++ b/source/reference/config/v20210101/app.txt @@ -0,0 +1,110 @@ +.. _appconfig-v20210101-app: + +======================= +App Configuration Files +======================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. include:: /reference/config/v20210101/note-old-version.rst + +You can configure high-level features of your application in +``realm_config.json``. + +.. code-block:: none + + app/ + └── realm_config.json + +Configuration +------------- + +.. code-block:: javascript + :caption: /realm_config.json + + { + "app_id": "", + "name": "", + "config_version": , + "environment": "", + "allowed_request_origins": ["", ...], + "deployment_model": "", + "location": "" + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``app_id`` + | String + - The application's :guilabel:`App ID`. + + * - | ``name`` + | String + - The application's name. + + .. include:: /includes/note-app-name-limitations.rst + + * - | ``config_version`` + | Number + + - The schema version that all configuration files in the application + conform to. This value is machine generated and you typically should not + manually set or modify it. + + * - | ``environment`` + | String + + - The name of the environment the app should + use when evaluating :ref:`environment values `. + + Valid options: + + .. include:: /includes/list-of-environment-names.rst + + Default: ``""`` + + * - | ``allowed_request_origins`` + | Document + - An array of URLs that incoming requests may originate from. If you define + any allowed request origins, then Atlas App Services blocks any incoming + request from an origin that is not listed. + + .. tip:: + + Request origins are URLs with the following form: + + .. code-block:: text + + ://[:port] + + * - | ``deployment_model`` + | String + - The application's :ref:`deployment model `. + + Valid options: + + - ``"GLOBAL"`` for :ref:`Global Deployment ` + - ``"LOCAL"`` for :ref:`Local Deployment ` + + * - | ``location`` + | String + - The name of the :ref:`cloud region ` that the application + is deployed in. + + - :ref:`Global applications ` process + all database writes in this region, but serve other application + requests in the nearest deployment region. + + - :ref:`Local applications ` process all + application requests and database writes in this region. diff --git a/source/reference/config/v20210101/auth.txt b/source/reference/config/v20210101/auth.txt new file mode 100644 index 000000000..a37d51d95 --- /dev/null +++ b/source/reference/config/v20210101/auth.txt @@ -0,0 +1,210 @@ +.. _appconfig-v20210101-auth: + +================================================== +User & Authentication Provider Configuration Files +================================================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. include:: /reference/config/v20210101/note-old-version.rst + +.. code-block:: none + + app/ + └── auth/ + ├── providers.json + └── custom_user_data.json + +.. _config-v20210101-auth-providers: + +Authentication Providers +------------------------ + +Configuration +~~~~~~~~~~~~~ + +You can enable and configure :ref:`authentication providers +` in ``/auth/providers.json``. + +Each field of the configuration is the name of a provider type and contains a +configuration object for that provider. Authentication provider configurations +share a common structure but each provider type uses a unique set of +configuration fields. + +.. tip:: + + You can find detailed information on a specific provider's configuration on + that provider's reference page. For a list of all provider reference pages, + see :ref:`Authentication Providers `. + +.. code-block:: javascript + :caption: /auth/providers.json + + { + "": { + "name": "", + "type": "", + "disabled": , + "config": { + "": "" + }, + "secret_config": { + "": "" + }, + "metadata_fields": [ + { + "required": , + "name": "Field Name" + }, + ... + ], + "redirect_uris": ["", ...] + }, + ... + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``name`` + | String + - The name of the authentication provider. This will always be the same as + the the provider's ``type``. + + * - | ``type`` + | String + - The authentication provider type. + + Valid options: + + - ``"anon-user"`` for :ref:`Anonymous ` authentication. + - ``"local-userpass"`` for :ref:`Email/Password ` authentication. + - ``"api-key"`` for :ref:`API Key ` authentication. + - ``"custom-token"`` for :ref:`Custom JWT ` authentication. + - ``"custom-function"`` for :ref:`Custom Function ` authentication. + - ``"oauth2-google"`` for :ref:`Google ` authentication. + - ``"oauth2-facebook"`` for :ref:`Facebook ` authentication. + - ``"oauth2-apple"`` for :ref:`Apple ID ` authentication. + + * - | ``disabled`` + | Boolean + - If ``true``, this authentication provider is not enabled for your + application. Users cannot log in using credentials for a disabled + provider. + + * - | ``config`` + | Document + - A document that contains configuration values that are specific + to the authentication provider. + + The following provider configurations include ``config``: + + - :ref:`Email/Password ` + - :ref:`Custom JWT ` + - :ref:`Custom Function ` + - :ref:`Google ` + - :ref:`Facebook ` + - :ref:`Apple ID ` + + * - | ``secret_config`` + | Document + - A document where each field name is a private configuration field + for the provider and the value of each field is the name of a + :ref:`Secret ` that stores the configuration value. + + The following provider configurations include ``redirect_uris``: + + - :ref:`Custom JWT ` + - :ref:`Google ` + - :ref:`Facebook ` + - :ref:`Apple ID ` + + * - | ``metadata_fields`` + | Array + - An array of documents where each document defines a metadata + field that describes the user. The existence of this field and + the exact format of each metadata field document depends on the + provider type. + + The following provider configurations include ``metadata_fields``: + + - :ref:`Custom JWT ` + - :ref:`Google ` + - :ref:`Facebook ` + + * - | ``redirect_uris`` + | Array + - A list of URLs that Atlas App Services may redirect user back to after + they complete an OAuth authorization. + + The following provider configurations include ``redirect_uris``: + + - :ref:`Google ` + - :ref:`Facebook ` + - :ref:`Apple ID ` + +.. _config-v20210101-custom-user-data: + +Custom User Data +---------------- + +You can configure the :ref:`custom user data ` +collection for your app in ``/auth/custom_user_data.json``. + +.. code-block:: javascript + :caption: /auth/custom_user_data.json + + { + "enabled": , + "mongo_service_name": "", + "database_name": "", + "collection_name": "", + "user_id_field": "", + "on_user_creation_function_name": "" + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field Name + - Description + + * - | ``enabled`` + | Boolean + + - If ``true``, App Services associates each user with a document in the specified + collection that contains their custom data. + + * - | ``mongo_service_name`` + | String + - The name of the :ref:`data source ` that contains + the custom user data collection. + + * - | ``database_name`` + | String + - The name of the database that contains the custom user data collection. + + * - | ``collection_name`` + | String + - The name of the collection that contains the custom user data. + + * - | ``user_id_field`` + | String + - The name of the field in custom user data documents that + contains the user ID of the application user the document + describes. + + * - | ``on_user_creation_function_name`` + | String + - The name of the :ref:`user creation function `. diff --git a/source/reference/config/v20210101/data_sources.txt b/source/reference/config/v20210101/data_sources.txt new file mode 100644 index 000000000..aff957c9e --- /dev/null +++ b/source/reference/config/v20210101/data_sources.txt @@ -0,0 +1,322 @@ +.. _appconfig-v20210101-data_sources: + +======================================= +MongoDB Data Source Configuration Files +======================================= + +.. default-domain:: mongodb + +.. include:: /reference/config/v20210101/note-old-version.rst + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. code-block:: none + + app/ + └── data_sources/ + └── / + ├── config.json + └── / + └── / + ├── schema.json + ├── relationships.json + └── rules.json + +Service Configuration +--------------------- + +.. _config-v20210101-mongodb-cluster: + +MongoDB Clusters +~~~~~~~~~~~~~~~~ + +.. code-block:: json + :caption: config.json + + { + "name": "", + "type": "mongodb-atlas", + "config": { + "clusterName": "", + "readPreference": "", + "wireProtocolEnabled": + } + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``name`` + | String + - Required. Default: ``mongodb-atlas`` + + The service name used to refer to the cluster within this Atlas App Services + app. The name may be at most 64 characters long and must only + contain ASCII letters, numbers, underscores, and hyphens. + + * - | ``type`` + | String + - Required. For MongoDB Atlas clusters, this value is always ``"mongodb-atlas"``. + + * - | ``config.clusterName`` + | String + - Required. The name of the cluster in Atlas. + + * - | ``config.readPreference`` + | String + - The :ref:`read preference ` mode for queries sent + through the service. + + .. include:: /mongodb/tables/read-preference-modes.rst + + * - | ``config.wireProtocolEnabled`` + | Boolean + - If ``true``, clients may :ref:`connect to the app over the MongoDB Wire + Protocol `. + +.. _config-v20210101-adf: + +{+adf-instance+}s +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: json + :caption: /data_sources//config.json + + { + "name": "", + "type": "datalake", + "config": { + "dataLakeName": "<{+adf-instance+} name>" + } + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``name`` + | String + - Required. Default: ``mongodb-datafederation`` + + The service name used to refer to the {+adf-instance+} within this App Services + app. The name may be at most 64 characters long and must only + contain ASCII letters, numbers, underscores, and hyphens. + + * - | ``type`` + | String + - Required. For a {+adf-instance+}, this value is always ``"datalake"``. + + * - | ``config.dataLakeName`` + | String + - Required. The name of the {+adf-instance+} in Atlas. + +Databases & Collections +----------------------- + +.. _config-v20210101-collection-schema: + +Collection Schema +~~~~~~~~~~~~~~~~~ + +If you want to enforce a :ref:`schema ` for a collection, define a +``schema.json`` configuration file that contains a JSON schema for the +documents. The root level schema must be an :ref:`object schema +`, which has the following form: + +.. code-block:: json + :caption: /data_sources////schema.json + + { + "title": "", + "bsonType": "object", + "properties": { + "": { }, + ... + } + } + +.. _config-v20210101-relationships: + +Relationships +~~~~~~~~~~~~~ + +.. code-block:: json + :caption: /data_sources////relationships.json + + { + "": { + "ref": "#/relationship///", + "source_key": "", + "foreign_key": "", + "is_list": + }, + ... + } + +.. list-table:: + :widths: 10 30 + :header-rows: 1 + + * - Field + - Description + + * - | ``ref`` + | String + - A JSON schema ``$ref`` string that specifies the foreign collection. The + string has the following form: + + .. code-block:: text + + #/relationship/// + + * - | ``source_key`` + | String + - The name of the field in this collection's schema that specifies which + documents in the foreign collection to include in the relationship. A + foreign document is included if ``source_key`` contains the value of its + ``foreign_key`` field. + + * - | ``foreign_key`` + | String + - The name of the field in the foreign collection's schema that contains + the value referenced by ``source_key``. + + * - | ``is_list`` + | Boolean + - If ``true``, the relationship may refer to multiple foreign documents + (i.e. a "to-many" relationship). The ``source_key`` field must be an + array with elements of the same type as the ``foreign_key`` field. + + If ``false``, the relationship may refer to zero or one foreign documents + (i.e. a "to-one" relationship). The ``source_key`` field must be the same + type as the ``foreign_key`` field. + +.. example:: + + An ecommerce app defines a relationship between two collections: each + document in ``store.orders`` references one or more documents in the + ``store.items`` collection by including item ``_id`` values in the order's + ``items`` array. Both collection are in the same linked cluster + (``mongodb-atlas``) and database (``store``). + + The relationship is defined for the ``orders`` collection: + + .. code-block:: json + :caption: /data_sources/mongodb-atlas/store/orders/relationships.json + + { + "items": { + "ref": "#/relationship/mongodb-atlas/store/items", + "source_key": "items", + "foreign_key": "_id", + "is_list": true + } + } + +.. _config-v20210101-default-rules: + +Default Rules +~~~~~~~~~~~~~ + +You can define default rules that apply to all collections in a data +source that don't have more specific :ref:`collection-level rules +` defined. + +You define default rules in the data source's ``default_rule.json`` +configuration file at ``data_sources//default_rule.json``. + +.. code-block:: json + :caption: /data_sources//default_rule.json + + { + "roles": [], + "filters": [] + } + +.. list-table:: + :widths: 10 30 + :header-rows: 1 + + * - Field + - Description + + * - | ``roles`` + | Array + - An array of :ref:`Role ` configurations. + + * - | ``filters`` + | Array + - An array of :ref:`Filter ` configurations. + +.. _config-v20210101-collection-rules: + +Collection Rules +~~~~~~~~~~~~~~~~ + +If the data source is not a :ref:`{+adf-datasource+} `, +then you can define collection-level rules in a collection's ``rules.json`` +configuration file. + +.. code-block:: json + :caption: /data_sources////rules.json + + { + "database": "", + "collection": "", + "roles": [], + "filters": [] + } + +.. list-table:: + :widths: 10 30 + :header-rows: 1 + + * - Field + - Description + + * - | ``database`` + | String + - The name of the database that holds the collection. + + * - | ``collection`` + | String + - The name of the collection. + + * - | ``roles`` + | Array + - An array of :ref:`Role ` configurations. + + * - | ``filters`` + | Array + - An array of :ref:`Filter ` configurations. + +.. _config-v20210101-rule: + +Rule Configurations +------------------- + +.. _config-v20210101-role: + +Roles +~~~~~ + +.. include:: /mongodb/tables/role-configuration.rst + + +.. _config-v20210101-filter: + +Filters +~~~~~~~ + +.. include:: /mongodb/tables/query-filter-params.rst diff --git a/source/reference/config/v20210101/environments.txt b/source/reference/config/v20210101/environments.txt new file mode 100644 index 000000000..dfa71634a --- /dev/null +++ b/source/reference/config/v20210101/environments.txt @@ -0,0 +1,57 @@ +.. _appconfig-v20210101-environment: + +===================================== +Environment Value Configuration Files +===================================== + +.. default-domain:: mongodb + +.. include:: /reference/config/v20210101/note-old-version.rst + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. code-block:: none + + app/ + └── environments/ + ├── no-environment.json + ├── development.json + ├── testing.json + ├── qa.json + └── production.json + +Environment Configuration +------------------------- + +You can define variable values for each :ref:`environment ` +in a ``.json`` file within the ``/environments`` directory that uses the +environment name as its file name. + +Atlas App Services supports the following environments: + +.. include:: /includes/list-of-environment-names.rst + +.. code-block:: json + :caption: environments/.json + + { + "values": { + "": + } + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``values`` + | Object + - An object where each property maps the name of an environment value name + to its value in the current environment. diff --git a/source/reference/config/v20210101/functions.txt b/source/reference/config/v20210101/functions.txt new file mode 100644 index 000000000..8e71953c3 --- /dev/null +++ b/source/reference/config/v20210101/functions.txt @@ -0,0 +1,125 @@ +.. _appconfig-v20210101-functions: + +============================ +Function Configuration Files +============================ + +.. default-domain:: mongodb + +.. include:: /reference/config/v20210101/note-old-version.rst + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. code-block:: none + + app/ + └── functions/ + ├── config.json + └── .js + +Function Manifest +----------------- + +Every :ref:`function ` in your app has a corresponding metadata entry +in the function manifest file: ``/functions/config.json``. + +.. tip:: + + Atlas App Services automatically adds functions to the manifest on import if + they don't already have a configuration defined. If you're okay with the + default settings, you can skip defining the configuration for a function and + let App Services do it for you. The manifest will include the generated + configurations the next time you export or pull your app. + +.. code-block:: json + :caption: functions/config.json + + [ + { + "name": "", + "private": , + "can_evaluate": { }, + "disable_arg_logs": , + "run_as_system": , + "run_as_user_id": "", + "run_as_user_id_script_source": "" + }, + ... + ] + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``name`` + | String + - The name of the function. The name must match the file name of a + :ref:`source code file ` and be unique among + all functions in your application. + + * - | ``private`` + | Boolean + - If ``true``, this function may only be called from other functions or in + :json-operator:`%function` rule expressions. You cannot call a private + function directly from a client application or with an SDK. + + * - | ``can_evaluate`` + | JSON Expression (default: ``true``) + - A :ref:`JSON expression ` that evaluates to ``true`` if the + function is allowed to execute. App Services evaluates this + expression for every incoming request. + + * - | ``disable_arg_logs`` + | Boolean + - If ``true``, App Services omits the arguments provided to the + function from the :ref:`function execution log entry `. + + * - | ``run_as_system`` + | Boolean + - If ``true``, this function :ref:`runs as the system user + `. This overrides any values defined for + ``run_as_user_id`` and ``run_as_user_id_script_source``. + + * - | ``run_as_user_id`` + | String + - The unique ID of a :doc:`App Services User ` that the + function always executes as. Cannot be used with + ``run_as_user_id_script_source``. + + * - | ``run_as_user_id_script_source`` + | String + - A stringified :doc:`function ` that runs whenever the + function is called and returns the unique ID of a :doc:`App Services + User ` that the function executes as. Cannot be used with + ``run_as_user_id``. + +.. _function-source-code-file: + +Function Source Code +-------------------- + +You define a function's source code in a ``.js`` file within the ``/functions`` +directory that uses the function name as its file name. Each file must export +the main function that runs whenever a request calls the function. + +.. important:: + + All of your function source code files must be in the ``/functions`` + directory. + +.. code-block:: javascript + :caption: /functions/.js + + exports = function addOne(input) { + if(typeof input !== "number") { + throw new Error("You must call addOne() with a number"); + } + return input + 1; + }; diff --git a/source/reference/config/v20210101/graphql.txt b/source/reference/config/v20210101/graphql.txt new file mode 100644 index 000000000..b76b0967a --- /dev/null +++ b/source/reference/config/v20210101/graphql.txt @@ -0,0 +1,173 @@ +.. _appconfig-v20210101-graphql: + +=========================== +GraphQL Configuration Files +=========================== + +.. default-domain:: mongodb + +.. include:: /reference/config/v20210101/note-old-version.rst + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +You can configure the :ref:`GraphQL API ` for your application in +the ``graphql`` directory: + +.. code-block:: none + + app/ + └── graphql/ + ├── config.json + └── custom_resolvers + └── .json + +Service Configuration +--------------------- + +.. code-block:: json + :caption: graphql/config.json + + { + "use_natural_pluralization": , + "disable_schema_introspection": + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``use_natural_pluralization`` + | Boolean + - ``true`` by default for new apps. + + You can only set the value to ``false`` when you :admin-api-endpoint:`create a new app with the Admin API endpoint ` + and pass the property into the body of the request. The value + cannot be changed to ``false`` once the app is created. + + If ``true``, generated schema type names use common English + pluralization whenever possible. + + If ``false``, or if a natural pluralization cannot be determined, + then plural types use the singular type name with an ``"s"`` + appended to the end. + + .. example:: + + App Services can use either a natural plural or a default plural for a + generated "mouse" type: + + - Natural: "mice" + - Default: "mouses" + + * - | ``disable_schema_introspection`` + | Boolean + - This value is ``false`` by default for new apps. + + If ``true``, the GraphQL API blocks :graphql:`introspection + queries ` from clients. + + This setting is useful for production Apps that do not want to + expose their GraphQL schema to the public. When introspection is + disabled, clients like GraphiQL cannot show docs for the API + schema or autocomplete queries and mutations. + +.. _appconfig-v20210101-custom-resolver: + +Custom Resolver Configuration +----------------------------- + +.. code-block:: json + :caption: graphql/custom_resolvers/.json + + { + "on_type": "", + "field_name": "", + "function_name": "", + "input_type": "" | { }, + "input_type_format": "", + "payload_type": "" | { }, + "payload_type_format": "", + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``on_type`` + | String + - The parent type that exposes the custom resolver as one of its fields. + + Valid Options: + + - ``"Query"`` (for :ref:`custom query ` operations) + - ``"Mutation"`` (for :ref:`custom mutation ` operations) + - A singular :ref:`exposed ` type name (for :ref:`computed properties `) + + * - | ``field_name`` + | String + - The name of the field on the parent type that exposes the custom + resolver. The field name must be unique among all custom resolver on its + parent type. + + If the field name matches a field in the parent type's schema, the custom + resolver overrides the schema type. + + * - | ``function_name`` + | String + - The name of the :ref:`function ` that runs when the + resolver is called. The function arguments may accept a single argument + (configured by ``input_type`` and ``input_type_format``) and must return + a payload value (configured by ``payload_type`` and + ``payload_type_format``). + + * - | ``input_type`` + | String | JSON Schema + - The type of the resolver's ``input`` argument (if it accepts input). You + can specify either the name of another type in your GraphQL schema or a + custom JSON schema specific to the resolver. + + * - | ``input_type_format`` + | String + - A metadata description of the ``input_type``. + + Valid Options: + + - ``"scalar"`` (for a single value of a specific BSON type) + - ``"scalar-list"`` (for multiple values of a specific BSON type) + - ``"generated"`` (for a single value of a specific :ref:`exposed ` type) + - ``"generated-list"`` (for multiple values of a specific :ref:`exposed ` type) + - ``"custom"`` (for a custom JSON schema) + + * - | ``payload_type`` + | String | JSON Schema + - The type of the value returned in the resolver's payload. You can specify + either the name of another type in your GraphQL schema or a custom JSON + schema specific to the resolver. + + If you do not specify a payload type, the resolver returns a + ``DefaultPayload`` object: + + .. literalinclude:: /includes/DefaultPayload.type.graphql + :language: graphql + + * - | ``payload_type_format`` + | String + - A metadata description of the ``payload_type``. + + Valid Options: + + - ``"scalar"`` (for a single value of a specific BSON type) + - ``"scalar-list"`` (for multiple values of a specific BSON type) + - ``"generated"`` (for a single value of a specific :ref:`exposed ` type) + - ``"generated-list"`` (for multiple values of a specific :ref:`exposed ` type) + - ``"custom"`` (for a custom JSON schema) diff --git a/source/reference/config/v20210101/hosting.txt b/source/reference/config/v20210101/hosting.txt new file mode 100644 index 000000000..0bf41a3d7 --- /dev/null +++ b/source/reference/config/v20210101/hosting.txt @@ -0,0 +1,126 @@ +.. _appconfig-v20210101-hosting: + +================================== +Static Hosting Configuration Files +================================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. include:: /reference/config/v20210101/note-old-version.rst + +.. code-block:: none + + app/ + └── hosting/ + ├── config.json + ├── metadata.json + └── files/ + └── + +Hosting Configuration +--------------------- + +You can enable and configure :doc:`static file hosting ` for your +application in ``hosting/config.json``. + +.. code-block:: json + :caption: config.json + + { + "enabled": , + "custom_domain": "", + "app_default_domain": "" + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field Name + - Description + + * - | ``enabled`` + | Boolean + - If ``true``, :doc:`static hosting ` is enabled for your app. + + * - | ``custom_domain`` + | String + - The :doc:`custom domain name ` for + your application's hosted files. + + * - | ``app_default_domain`` + | String + - The default domain for your application's hosted files. Atlas App Services + automatically sets this value and you cannot change it. + +File Metadata +------------- + +You can define metadata for any hosted file by adding an entry to +``hosting/metadata.json``. + +.. code-block:: json + :caption: metadata.json + + [ + { + "path": "", + "attrs": [ + { + "name": "", + "value": "" + }, + ... + ] + }, + ... + ] + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``path`` + | String + - The :ref:`resource path ` of the file. + + * - | ``attrs`` + | Array + - An array of documents where each document represents a single + metadata attribute. Attribute documents have the following form: + + .. code-block:: json + :caption: Metadata Attribute Document + + { + "name": "", + "value": "" + } + + .. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``name`` + | String + - The name of the metadata attribute. This should be one of + the :doc:`file metadata attributes + ` that App Services supports. + + * - | ``value`` + | String + - The value of the metadata attribute. + +.. include:: /hosting/includes/note-infer-content-type.rst diff --git a/source/reference/config/http_endpoints.txt b/source/reference/config/v20210101/http_endpoints.txt similarity index 98% rename from source/reference/config/http_endpoints.txt rename to source/reference/config/v20210101/http_endpoints.txt index d88802b63..5aec075b2 100644 --- a/source/reference/config/http_endpoints.txt +++ b/source/reference/config/v20210101/http_endpoints.txt @@ -1,4 +1,4 @@ -.. _appconfig-http_endpoints: +.. _appconfig-v20210101-http_endpoints: ================================= HTTP Endpoint Configuration Files @@ -6,6 +6,8 @@ HTTP Endpoint Configuration Files .. default-domain:: mongodb +.. include:: /reference/config/v20210101/note-old-version.rst + .. code-block:: none app/ @@ -21,7 +23,7 @@ HTTP Endpoint Configuration Files ├── config.json └── source.js -.. _appconfig-endpoints: +.. _appconfig-v20210101-endpoints: Custom HTTPS Endpoint Configuration ----------------------------------- @@ -141,7 +143,7 @@ endpoints ` as an array in ``http_endpoints/config.json``. - Enables (``false``) or disables (``true``) the endpoint. -.. _appconfig-data-api-endpoints: +.. _appconfig-v20210101-data-api-endpoints: Data API Configuration ---------------------- @@ -303,7 +305,7 @@ with the same name as the rule. - A :ref:`rule expression ` that evaluates to ``true`` when the rule applies to a given request. -.. _config-incoming-webhooks: +.. _config-v20210101-incoming-webhooks: [Deprecated] Incoming Webhooks ------------------------------ diff --git a/source/reference/config/v20210101/log_forwarders.txt b/source/reference/config/v20210101/log_forwarders.txt new file mode 100644 index 000000000..bbe9c10e9 --- /dev/null +++ b/source/reference/config/v20210101/log_forwarders.txt @@ -0,0 +1,100 @@ +.. _appconfig-v20210101-log_forwarders: + +================================= +Log Forwarder Configuration Files +================================= + +.. default-domain:: mongodb + +.. include:: /reference/config/v20210101/note-old-version.rst + +You define log forwarder configuration files in the ``/log_forwarders`` +directory. + +.. code-block:: none + + app/ + └── log_forwarders/ + └── .json + +.. code-block:: json + :caption: log_forwarders/.json + + { + "name": "", + "log_types": [ "", ... ], + "log_statuses": [ "", ... ], + "policy": { batching policy }, + "action": { action configuration } + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``name`` + | String + - A unique name for the log forwarder. + + * - | ``log_types`` + | Array + - An array of one or more log types that the forwarder should + send to a service. Atlas App Services only forwards a log if its type is + listed *and* its status is listed in ``log_statuses``. + + The array may contain the following log types: + + .. include:: /includes/log-forwarder-types.rst + + * - | ``log_statuses`` + | Array + - An array of one or more log statuses that the forwarder should + send to a service. App Services only forwards a log if its type is + listed *and* its type is listed in ``log_types``. + + The array may contain the following log statuses: + + .. include:: /includes/log-forwarder-statuses.rst + + * - | ``policy`` + | Object + - An object that configures the forwarder's batching policy. + + To forward logs individually: + + .. code-block:: json + + { "type": "single" } + + To group logs into batches: + + .. code-block:: json + + { "type": "batch" } + + * - | ``action`` + | Object + - An object that configures where and how the forwarder sends logs. + + To forward logs to a linked MongoDB collection: + + .. code-block:: json + + { + "type": "collection", + "data_source": "", + "database": "", + "collection": "" + } + + To forward logs with a custom function: + + .. code-block:: json + + { + "type": "function", + "name": "" + } diff --git a/source/reference/config/v20210101/note-old-version.rst b/source/reference/config/v20210101/note-old-version.rst new file mode 100644 index 000000000..a50615a2a --- /dev/null +++ b/source/reference/config/v20210101/note-old-version.rst @@ -0,0 +1,10 @@ +.. note:: + + This page describes a legacy configuration file format. You should + only use this information if you're using the deprecated + ``realm-cli``. + + Any configuration files you pull with {+cli+} or export from the UI + use the latest configuration version. For detailed information on the + current configuration file format, see :ref:`App Configuration + `. diff --git a/source/reference/config/services.txt b/source/reference/config/v20210101/services.txt similarity index 96% rename from source/reference/config/services.txt rename to source/reference/config/v20210101/services.txt index ced58ef98..cd43c65a8 100644 --- a/source/reference/config/services.txt +++ b/source/reference/config/v20210101/services.txt @@ -1,4 +1,4 @@ -.. _appconfig-services: +.. _appconfig-v20210101-services: ======================================= Third-Party Service Configuration Files @@ -6,6 +6,8 @@ Third-Party Service Configuration Files .. default-domain:: mongodb +.. include:: /reference/config/v20210101/note-old-version.rst + .. code-block:: none app/ diff --git a/source/reference/config/v20210101/sync.txt b/source/reference/config/v20210101/sync.txt new file mode 100644 index 000000000..4b41489cb --- /dev/null +++ b/source/reference/config/v20210101/sync.txt @@ -0,0 +1,24 @@ +===================================== +Atlas Device Sync Configuration Files +===================================== + +.. default-domain:: mongodb + +.. include:: /reference/config/v20210101/note-old-version.rst + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +You can configure :ref:`Atlas Device Sync ` for your application in the ``sync`` +directory: + +.. code-block:: none + + app/ + └── sync/ + └── config.json + +Refer to :ref:`appconfig-sync` for details. diff --git a/source/reference/config/v20210101/triggers.txt b/source/reference/config/v20210101/triggers.txt new file mode 100644 index 000000000..c1ed7b373 --- /dev/null +++ b/source/reference/config/v20210101/triggers.txt @@ -0,0 +1,316 @@ +.. _appconfig-v20210101-triggers: + +=========================== +Trigger Configuration Files +=========================== + +.. default-domain:: mongodb + +.. include:: /reference/config/v20210101/note-old-version.rst + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. code-block:: none + + app/ + └── triggers/ + └── .json + +.. _config-v20210101-trigger: + +General Configuration +--------------------- + +All triggers conform to a base schema with specific variations depending on the +trigger type. The following fields exist in *all* trigger configuration files: + +.. code-block:: json + :caption: triggers/.json + + { + "name": "", + "type": "", + "config": {}, + "function_name": "", + "disabled": + } + +.. list-table:: + :widths: 10 30 + :header-rows: 1 + + * - Field + - Description + + * - | ``name`` + | String + - The trigger name. This may be at most 64 characters + long and can only contain ASCII letters, numbers, underscores, + and hyphens. + + * - | ``type`` + | String + - The trigger type. The value of this field determines the exact + configuration file schema. + + Valid Options: + + - ``"DATABASE"`` + - ``"AUTHENTICATION"`` + - ``"SCHEDULED"`` + + * - | ``config`` + | Document + - A document with fields that map to additional configuration options for + the trigger. The exact configuration fields depend on the trigger + ``type``: + + - :ref:`Database Triggers ` + - :ref:`Authentication Triggers ` + - :ref:`Scheduled Triggers ` + + * - | ``function_name`` + | String + - The name of the :ref:`Atlas Function ` that the + trigger executes whenever it fires. + + * - | ``event_processors`` + | Document + - A document that configures the trigger to send events to external event + processors whenever it fires. Cannot be used with ``function_name``. + + For more information, see :ref:`Send Trigger Events to AWS EventBridge + `. + + * - | ``disabled`` + | Boolean + - If ``true``, the trigger will not listen for any events and will + not fire. + +.. _config-v20210101-database-trigger: + +Database Triggers +----------------- + +Database trigger configurations conform to the base trigger schema with +additional configuration options that specify which collection to watch and when +to fire the trigger. The following fields exist in *database* trigger +configuration files: + +.. code-block:: json + :caption: triggers/.json + + { + "name": "", + "type": "DATABASE", + "config": { + "service_name": "", + "database": "", + "collection": "", + "operation_types": ["", ...], + "full_document": , + "full_document_before_change": , + "tolerate_resume_errors": , + "unordered": , + "match": { }, + "project": { }, + }, + "function_name": "", + "disabled": + } + +.. list-table:: + :widths: 10 30 + :header-rows: 1 + + * - Field + - Description + + * - | ``config.service_name`` + | String + + - The name of the :ref:`MongoDB data source ` + that contains the watched collection. You cannot define a database + trigger on a :ref:`serverless instance ` or + :ref:`{+adf-instance+} `. + + * - | ``config.database`` + | String + - The name of the MongoDB database that contains the watched collection. + + * - | ``config.collection`` + | String + - The name of the collection that the trigger watches. + + * - | ``config.operation_types`` + | String[] + - A list of one or more :ref:`database operation + types ` that cause the trigger to fire. + + Valid operations types: + + - ``"INSERT"`` + - ``"UPDATE"`` + - ``"REPLACE"`` + - ``"DELETE"`` + + .. tip:: + + Update operations executed from MongoDB Compass or the MongoDB Atlas Data + Explorer fully replace the previous document. As a result, update + operations from these clients will generate ``REPLACE`` change events + rather than ``UPDATE`` events. + + * - | ``config.full_document`` + | Boolean + - If ``true``, ``UPDATE`` change events include the latest + :manual:`majority-committed ` version + of the modified document *after* the change was applied in the + ``fullDocument`` field. + + .. note:: + + Regardless of this setting: + + - ``INSERT`` and ``REPLACE`` events always include the + ``fullDocument`` field. + + - ``DELETE`` events never include the ``fullDocument`` field. + + * - | ``config.full_document_before_change`` + | Boolean + - If ``true``, change events include a copy of the modified document + from immediately *before* the change was applied in the + ``fullDocumentBeforeChange`` field. All change events except for + ``INSERT`` events include the document preimage. + + .. important:: Collection-Level Preimage Settings + + Document preimages use extra information stored in the oplog. + The extra data may have performance implications for some apps. + + Once you've enabled document preimages for any trigger on a + given collection, that collection will include preimage data in + the oplog and other triggers on the collection can use preimages + with no additonal overhead. + + You can disable document preimages on a per-trigger basis to + exclude the preimage from change events. Regardless of your + trigger-level settings, a collection's oplog entries will + continue to include preimage data unless you explicitly disable + preimages for the collection. + + For more information, see :ref:`preimages`. + + * - | ``config.tolerate_resume_errors`` + | Boolean + - If ``true``, the Trigger automatically resumes if the token + required to process change stream events cannot be found. + + .. include:: /includes/trigger-auto-resume.rst + + For more information on resuming suspended Triggers, see + :ref:`Suspended Triggers `. + + * - | ``config.unordered`` + | Boolean + - If ``true``, indicates that event ordering is disabled for this trigger. + + .. include:: /includes/trigger-event-ordering.rst + + * - | ``config.match`` + | Document + - .. include:: /includes/trigger-match-expression.rst + + * - | ``config.project`` + | Document + - .. include:: /includes/trigger-project-expression.rst + +.. _config-v20210101-authentication-trigger: + +Authentication Triggers +----------------------- + +Authentication trigger configurations conform to the base trigger schema with +additional configuration options that specify which auth providers to watch and +when to fire the trigger. The following fields exist in *authentication* trigger +configuration files: + +.. code-block:: json + :caption: triggers/.json + + { + "name": "", + "type": "AUTHENTICATION", + "config": { + "operation_type": ["", ...], + "providers": ["", ...], + }, + "function_name": "", + "disabled": + } + +.. list-table:: + :widths: 10 30 + :header-rows: 1 + + * - Field + - Description + + * - | ``config.operation_type`` + | String + - The :ref:`authentication operation type + ` that causes the trigger to fire. + + Valid operations types: + + - ``"LOGIN"`` + - ``"CREATE"`` + - ``"DELETE"`` + + * - | ``config.providers`` + | String[] + - A list of :ref:`authentication provider ` types + that the trigger watches. + + Valid provider types: + + .. include:: /includes/auth-provider-internal-names.rst + +.. _config-v20210101-scheduled-trigger: + +Scheduled Triggers +------------------ + +Scheduled trigger configurations conform to the base trigger schema with +additional configuration options that specify the schedule on which the trigger +fires. The following fields exist in *scheduled* trigger configuration files: + +.. code-block:: json + :caption: triggers/.json + + { + "name": "", + "type": "SCHEDULED", + "config": { + "schedule": "" + }, + "function_name": "", + "disabled": + } + +.. list-table:: + :widths: 10 30 + :header-rows: 1 + + * - Field + - Description + + * - | ``config.schedule`` + | String + - The :ref:`CRON expression ` that + schedules the trigger's execution. diff --git a/source/reference/config/v20210101/values.txt b/source/reference/config/v20210101/values.txt new file mode 100644 index 000000000..b18e4613f --- /dev/null +++ b/source/reference/config/v20210101/values.txt @@ -0,0 +1,70 @@ +.. _appconfig-v20210101-values: + +========================= +Value Configuration Files +========================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. include:: /reference/config/v20210101/note-old-version.rst + +You can define static :ref:`values ` in the ``/values`` directory. +Each value is defined in its own JSON file with the same name as the value. + +.. code-block:: none + + app/ + └── values/ + └── .json + +Configuration +------------- + +.. code-block:: json + :caption: .json + + { + "id": "", + "name": "", + "from_secret": , + "value": + } + +.. list-table:: + :header-rows: 1 + :widths: 10 30 + + * - Field + - Description + + * - | ``id`` + | String + - A string that uniquely identifies the value. Atlas App Services automatically + generates a unique ID for a value when you create it. + + * - | ``name`` + | String + - A unique name for the value. This name is how you refer to + the value in functions and rules. + + * - | ``from_secret`` + | Boolean + - Default: ``false``. If ``true``, the value exposes a + :ref:`Secret ` instead of a plain-text JSON value. + + * - | ``value`` + | String, Array, or Object + - The stored data that App Services exposes when the value is referenced. + + If ``from_secret`` is ``false``, ``value`` can be a standard + JSON string, number, array, or object. + + If ``from_secret`` is ``true``, ``value`` is a string that + contains the name of the :ref:`Secret ` that the + value exposes. diff --git a/source/reference/config/values.txt b/source/reference/config/values.txt index 18ad62e3f..4af4954fc 100644 --- a/source/reference/config/values.txt +++ b/source/reference/config/values.txt @@ -42,26 +42,26 @@ Configuration - Description * - | ``id`` - | String + | ``string`` - A string that uniquely identifies the value. Atlas App Services automatically generates a unique ID for a value when you create it. * - | ``name`` - | String + | ``string`` - A unique name for the value. This name is how you refer to the value in functions and rules. * - | ``from_secret`` - | Boolean + | ``boolean`` - Default: ``false``. If ``true``, the value exposes a :ref:`Secret ` instead of a plain-text JSON value. * - | ``value`` - | String, Array, or Object + | ``any`` - The stored data that App Services exposes when the value is referenced. If ``from_secret`` is ``false``, ``value`` can be a standard - JSON string, array, or object. + JSON string, number, array, or object. If ``from_secret`` is ``true``, ``value`` is a string that contains the name of the :ref:`Secret ` that the diff --git a/source/reference/partition-based-sync.txt b/source/reference/partition-based-sync.txt index 845a3306e..680023db5 100644 --- a/source/reference/partition-based-sync.txt +++ b/source/reference/partition-based-sync.txt @@ -524,7 +524,7 @@ Procedure .. code-block:: shell - realm-cli push --remote="" + {+cli-bin+} push --remote="" .. tab:: :tabid: api diff --git a/source/reference/template-apps.txt b/source/reference/template-apps.txt index e1198b65e..3073c5620 100644 --- a/source/reference/template-apps.txt +++ b/source/reference/template-apps.txt @@ -66,7 +66,7 @@ option is most convenient for you. .. code-block:: shell - realm-cli apps create \ + {+cli-bin+} apps create \ --name "" \ --template "