Navigation

Create a Realm App with Realm CLI

On this page

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.

Prerequisites

Procedure

1

Create an Application Directory

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

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

echo \{\} > config.json

Note

Upon successfully creating a new Realm app, realm-cli will immediately update config.json to reflect the new app.

This overwrites any existing values in config.json.

2

Optional: Initialize Application Entities

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 Application Configuration Files.

Note

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.

3

Authenticate a MongoDB Atlas User

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>"
4

Run the Import Command

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:

Field Description
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.

Note

realm-cli converts application names to lowercase.

5

Verify Application Creation

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

Note

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.