Create a Realm App with Realm CLI

MongoDB Realm applications can be created and initialized with the realm-cli import command.

Create a new Realm app by running import from an application directory that cannot be linked to an existing application by Application ID.


Create a new directory for your application and navigate into it.

Add a realm_config.json file to the root level of the directory. The file should contain an empty JSON object.

echo \{\} > realm_config.json

When you import your new app, realm-cli overwrites realm_config.json with the app's metadata.


If you'd like to pre-configure any services in your application (including linking to a specific MongoDB Atlas cluster), create sub-directories and configuration files for those entities in the application directory. For details on the directory structure and contents, see Realm Application Configuration.


If you are importing any new entities that require a Secret (e.g. auth tokens, client secrets, etc.), you must create those before you import the entities. You can create a secret with Realm CLI or through the Realm UI.


To create a Realm app with realm-cli, users must authenticate with Atlas using an API Key.

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

Run the following command in your application directory:

realm-cli import

Before importing, realm-cli will search existing applications that the authenticated user has access to. If app_id was not provided or does not match any existing application, realm-cli will ask you if you'd like to create a new Realm app. After you confirm, realm-cli will prompt you for the following information:

Atlas Project ID
The Project ID or Project Name of the Atlas project that you want to host your Realm app. You can find these values on the Settings page of the Atlas UI.
App Name

The name of your application.

Application names may only contain ASCII letters, numbers, underscores, and hyphens.

realm-cli converts application names to lowercase.

You can confirm that your new Realm app was successfully imported by checking realm_config.json. If the creation was successful, the app_id and name fields will have updated values that reflect the new application.


New application imports happen in two phases:

  1. A new application is created on the server.
  2. The local application directory is imported to the new application.

It's possible for realm-cli to successfully create a new app but then throw an error during the import phase. In this case, no entities are imported but the new application is not deleted. If you encounter this, fix any errors causing the import to fail and run the import command again.

Give Feedback