realm-cli v1 [Deprecated]

Authenticate a CLI User

Use realm-cli login to authenticate a MongoDB Cloud user with a MongoDB Atlas programmatic API Key.

realm-cli login --api-key="<my api key>" --private-api-key="<my private api key>"

--api-key <api key>

A valid public MongoDB Atlas programmatic API key for the MongoDB Cloud account you wish to log in with.

--private-api-key <private api key>

A valid private MongoDB Atlas programmatic API key for the MongoDB Cloud account you wish to log in with.

--username <MongoDB Cloud username>

(Deprecated) The username of the MongoDB Cloud account you wish to log in with using personal API keys.

Log Out the Current CLI User

Use realm-cli logout to log out the currently logged in user.

realm-cli logout

View the Currently Logged In User

Use realm-cli whoami to see details on the user that is currently logged in to the CLI, if applicable.

realm-cli whoami

If there is a currently logged-in user, their information will display on the next line in the following format:

<username> [API Key: ********-****-****-****-<last 12 digits of API key>]

If no user is logged in, realm-cli will return the following message:

no user info available

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, realm-cli can create the application for you.

realm-cli import \
  --app-id=myapp-abcde \
  --path=./path/to/app/dir \
  --strategy=merge \
  --include-hosting \
  --include-dependencies

--app-id <App Services Application ID>

Optional.

The Application ID of your App.

If not specified, realm-cli will attempt to use the value of app_id defined in config.json. If 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 realm-cli, App Services generates a new App ID and ignores any value that you specify for the --app-id flag.

--path <path>

Optional.

The path to the directory containing files you wish to import. The directory must contain, at minimum, a valid config.json file.

If the path argument is omitted, realm-cli will search for a config.json file in the current application directory.

--strategy ['merge|replace|replace-by-name']

Optional.

Default: Merge

The import strategy that realm-cli should use when reconciling imported entities.

--project-id <MongoDB Cloud Project ID>

Optional.

The Project ID of the Atlas project on which you want to host a newly created App. If specified, realm-cli will not prompt you to select a project when creating a new app.

Note

realm-cli ignores the value of --project-id unless you are importing a new application.

--include-hosting

Optional.

If specified, uploads and deploys any static assets in the /hosting/files directory of your App.

--include-dependencies

Optional.

If specified, uploads and deploys any external dependencies included in a node_modules archive in the /functions directory of your App.

Export an Application

Use realm-cli export to save an App configuration to a local application directory.

realm-cli export \
  --app-id=myRealmApp-abcde \
  --output=path/to/exported/app/dir \
  --include-hosting \
  --as-template

--app-id <App Services Application ID>

Optional.

The Application ID of your App.

--output <path>

Optional.

The path of the directory where App Services will export your application.

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, realm-cli will export the application configuration to a new directory within the current working directory.

--include-hosting

Optional.

If specified, exports all hosted static assets in the hosting/files directory of your App.

--for-source-control

Optional.

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 config.json of any Atlas data sources linked to the application.

--as-template

Optional.

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.

Diff Pending Application Changes

Use realm-cli diff to return a diff of the configuration files between the deployed application and your local application directory.

# Diff application config files
realm-cli diff
# Diff application config files and hosted files
realm-cli diff --include-hosting

The diff resembles the following:

--- functions/oldFunctionName/config.json
+++ functions/oldFunctionName/config.json
@@ -1,6 +1 @@
-{
-    "id": "5d4c6a5cd28e555496a705da",
-    "name": "oldFunctionName",
-    "private": false
-}
--- functions/newFunctionName/config.json
+++ functions/newFunctionName/config.json
@@ -1 +1,6 @@
+{
+    "id": "5d4c6a5cd28e555496a705da",
+    "name": "newFunctionName",
+    "private": false
+}
Modified Files:
        * /index.html
        * /auth/confirmEmail.html
        * /auth/resetPassword.html

--include-hosting

Optional.

If specified, the diff includes a list of files in the hosting/files directory of your App that are different from your app's deployed files.

List All Secrets

Use realm-cli secrets list to return a list that contains the Name and ID of each Secret in your application.

realm-cli secrets list

The returned list of secrets resembles the following:

ID                       Name
5d5c25415e30c7ef857c6a10 test-secret-please-ignore
5d56dd453b467e2a48a6ec32 some-other-secret

Create a Secret

Use realm-cli secrets add to create a new Secret with the specified name and value.

realm-cli secrets add --name=mySecret --value=SuperSecretValue!

--name <Secret Name>

A unique name for the new Secret. If an existing Secret already has the specified name then this operation will fail.

--value <Secret Value>

The value of the new Secret.

Update a Secret's Value

Use realm-cli secrets update to change the value of an existing Secret in your application.

# Update a Secret by name
realm-cli secrets update --secret-name=mySecret --value=NewSecretValue
realm-cli secrets update --name=mySecret --value=NewSecretValue
# Update a Secret by name
realm-cli secrets update --secret-id=5ba9c5c2e707c02b38031412 --value=NewSecretValue
realm-cli secrets update --id=5ba9c5c2e707c02b38031412 --value=NewSecretValue

--secret-name <Secret Name>

--name <Secret Name>

The name of the Secret to update.

--secret-id <Secret ID>

--id <Secret ID>

The ID value of the Secret to update.

--value <Secret Value>

The new value of the Secret.

Remove a Secret

Use realm-cli secrets remove to delete an existing Secret from your application.

# Remove a Secret by name
realm-cli secrets remove --secret-name=mySecret
realm-cli secrets remove --name=mySecret
# Remove a Secret by ID
realm-cli secrets remove --secret-id=5ba9c5c2e707c02b38031412
realm-cli secrets remove --id=5ba9c5c2e707c02b38031412

--secret-name <Secret Name>

--name <Secret Name>

The name of the Secret to remove from your App.

--secret-id <Secret ID>

--id <Secret ID>

The ID value of the Secret to remove from your App.

Merge

realm-cli import --strategy=merge

Under the merge strategy, entities in the application directory are added to the application non-destructively. Any existing entities in an application are left unchanged if they are not represented in the imported application directory.

If an imported entity's id value matches the id of an existing entity, the existing entity will be updated to match the imported entity. App Services assigns system-generated id values to entities without id values before importing them as new entities.

If an entity is imported with an id that does not match an existing entity, the import will fail. Importing an entity with a non-ObjectID id value causes an error.

{ "id": <ObjectID 1>, "name": "FunctionA", ... }
{ "id": <ObjectID 2>, "name": "FunctionB", ... }
{ "id": <ObjectID 3>, "name": "FunctionC", ... }

{ "id": <ObjectID 1>, "name": "FunctionA_Updated!", ... }
{ "name": "FunctionD", ... }

{ "id": <ObjectID 1>, "name": "FunctionA_Updated!" }
{ "id": <ObjectID 2>, "name": "FunctionB", ... }
{ "id": <ObjectID 3>, "name": "FunctionC", ... }
{ "id": <ObjectID 4>, "name": "FunctionD", ... }

Replace

realm-cli import --strategy=replace

Under the replace strategy, if an imported entity's id value matches the id of an existing entity, App Services replaces the existing entity with the imported entity. If an imported entity's id value does not match an existing entity, the import fails. If an existing entity's id does not match the id of any imported entity, App Services deletes that existing entity.

App Services generates id values for entities that lack id values before importing them as new entities. Importing an entity with a non-ObjectID id value does not throw an error.

{ "id": <ObjectID 1>, "name": "FunctionA", ... }
{ "id": <ObjectID 2>, "name": "FunctionB", ... }
{ "id": <ObjectID 3>, "name": "FunctionC", ... }

{ "id": <ObjectID 1>, "name": "FunctionA_Updated!", ... }
{ "name": "FunctionD", ... }
{ "id": "non-ObjectID-value", "name": "FunctionE", ... }

{ "id": <ObjectID 1>, "name": "FunctionA_Updated!" }
{ "id": <ObjectID 4>, "name": "FunctionD", ... }
{ "id": <ObjectID 5>, "name": "FunctionE", ... }

Replace by Name

realm-cli import --strategy=replace-by-name

Under the replace-by-name strategy, if an imported entity's name value matches the name of an existing entity, App Services replaces the existing entity with the imported entity. If an imported entity's name value does not 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, realm-cli will throw an error.

{ "id": <ObjectID 1>, "name": "FunctionA", ... }
{ "id": <ObjectID 2>, "name": "FunctionB", ... }
{ "id": <ObjectID 3>, "name": "FunctionC", ... }

{ "name": "FunctionZ", ... }
{ "name": "FunctionB", ... }
{ "name": "FunctionC", ... }

{ "id": <ObjectID 2>, "name": "FunctionB", ... }
{ "id": <ObjectID 3>, "name": "FunctionC", ... }
{ "id": <ObjectID 4>, "name": "FunctionZ", ... }