Stitch CLI¶

On this page

Overview¶

stitch-cli¶

The MongoDB Stitch Command Line Interface (stitch-cli) allows you to programmatically manage your MongoDB Stitch applications. With stitch-cli, you can create or update Stitch applications from a local directory as well as export existing applications to a local directory.

Installation¶

npm / Yarn
Manual Install

The easiest way to install stitch-cli is with the npm package manager. Ensure that you have Node.js installed, then run the following command in your shell:

copy

npm install -g mongodb-stitch-cli

You can also install the CLI from npm with Yarn:

copy

yarn global add mongodb-stitch-cli

1

Download the `stitch-cli` binary¶

You can download the stitch-cli binary directly from the Stitch UI.

Navigate to the Deploy page from the left-hand navigation.
Select the Import/Export tab.
In the Download CLI Client section, select the operating system on which you want to install stitch-cli. The CLI binary should begin downloading immediately.

../../_images/download-cli-stitch-ui.png

2

Add the `stitch-cli` binary to your system PATH¶

Linux / macOS
Windows

When you call stitch-cli from the command line, your shell searches each directory listed in your PATH environment variable for the stitch-cli executable binary.

Move the stitch-cli binary file from your downloads folder to a directory listed in your PATH.

copy

mv /path/to/downloads/stitch-cli /usr/local/bin/stitch-cli

You can check which directories are listed in your PATH by running the following from the command line:

copy

echo $PATH

To add a directory to your path, add the following to the bottom of your shell rc file (e.g. ~/.bashrc), substituting in the path of the directory you’d like to add:

copy

export PATH=${PATH}:path/to/directory

When you call stitch-cli.exe from the command line, your system searches each directory listed in your %PATH% environment variable for the stitch-cli executable file.

Move stitch-cli.exe to a directory that is listed in %PATH%.

You can check which directories are listed in %PATH% as well as add new directories from the Environment Variables configuration window. You can find this window by searching for “Environment Variables” or by following these steps:

Depending on which version of Windows you’re running, right click My Computer or This PC and select Properties.
Click Advanced Properties, then Environment Variables.

In the Environment Variables window, your PATH variable is listed under System Variables.

3

(Linux / macOS) Configure execution permissions for `stitch-cli`¶

On Linux and Mac systems, no user has execution permissions for stitch-cli by default. To add execution permissions, run the following command:

copy

chmod +x path/to/stitch-cli

To confirm that stitch-cli has execution permissions, navigate to the directory containing the binary and run the following command:

copy

ls -l | grep "stitch-cli"

The output of this command should resemble the following:

-rwxrwxr-x@  1 user  staff      9443152 Mar  6 12:01 stitch-cli

The ls -l command lists the file’s permissions followed by some additional information. If the permissions string in your output includes the letter x then you have successfully configured execution permissions. If no x is present (e.g. -rw-r--r--@) you did not successfully configure execution permissions and should run the chmod command as described above.

General Options¶

The following options are available for all stitch-cli commands:

--config-path <File System Path>¶

Optional.

If included with stitch-cli login, stores information about the authenticated session in a file at the specified path. Session information includes your MongoDB Cloud username, API Key, and a session refresh token.

If included with any other command, authenticates the request with the session saved at the specified path (if it exists) instead of the current CLI authentication state.

--disable-color¶

Optional.

If specified, suppress all text color in stitch-cli output.

By default, some output such as errors and import diffs are colorized. Use this flag if you wish to prevent this behavior.

--yes¶: Optional.

If specified, automatically respond affirmatively to any yes/no prompts from stitch-cli.

Authentication¶

Authenticate a CLI User¶

stitch-cli login¶

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

copy

stitch-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¶

stitch-cli logout¶

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

copy

stitch-cli logout

View the Currently Logged In User¶

stitch-cli whoami¶

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

copy

stitch-cli whoami

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

copy

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

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

copy

no user info available

Stitch Applications¶

Import an Application¶

stitch-cli import¶

Use stitch-cli import to import a local application directory into a hosted Stitch application. If you import a directory into an application that doesn’t exist, stitch-cli can create the application for you.

copy

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

--app-id <MongoDB Stitch Application ID>¶

Optional.

The Application ID of your MongoDB Stitch application.

If not specified, stitch-cli will attempt to use the value of app_id defined in stitch.json. If stitch.json does not have an app_id value, stitch-cli prompts you to create a new application.

New Application App IDs

If you create a new application with stitch-cli, Stitch 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 stitch.json file.

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

--strategy ['merge|replace|replace-by-name']¶: Optional.

Default: Merge

The import strategy that stitch-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 Stitch application. If specified, stitch-cli will not prompt you to select a project when creating a new app.

Note

stitch-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 Stitch application.

--include-dependencies¶: Optional.

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

Export an Application¶

stitch-cli export¶

Use stitch-cli export to save a Stitch application configuration to a local application directory.

copy

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

--app-id <MongoDB Stitch Application ID>¶: Optional.

The Application ID of your MongoDB Stitch application.

--output <path>¶

Optional.

The path of the directory where Stitch will export your application.

If specified, stitch-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, stitch-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 Stitch application.

--for-source-control¶: Optional.

If enabled, stitch-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 stitch.json file as well as the config.clusterName field in the config.json of any Atlas clusters linked to the application.

--as-template¶: Optional.

If enabled, stitch-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¶

stitch-cli diff¶

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

copy

# Diff application config files
stitch-cli diff

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

The diff resembles the following:

copy

--- 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 Stitch application that are different from your app’s deployed files.

Secrets¶

List All Secrets¶

stitch-cli secrets list¶

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

copy

stitch-cli secrets list

The returned list of secrets resembles the following:

copy

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

Create a Secret¶

stitch-cli secrets add¶

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

copy

stitch-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¶

stitch-cli secrets update¶

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

copy

# Update a Secret by name
stitch-cli secrets update --secret-name=mySecret --value=NewSecretValue
stitch-cli secrets update --name=mySecret --value=NewSecretValue

# Update a Secret by name
stitch-cli secrets update --secret-id=5ba9c5c2e707c02b38031412 --value=NewSecretValue
stitch-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¶

stitch-cli secrets remove¶

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

copy

# Remove a Secret by name
stitch-cli secrets remove --secret-name=mySecret
stitch-cli secrets remove --name=mySecret

# Remove a Secret by ID
stitch-cli secrets remove --secret-id=5ba9c5c2e707c02b38031412
stitch-cli secrets remove --id=5ba9c5c2e707c02b38031412

--secret-name <Secret Name>¶

--name <Secret Name>¶: The name of the Secret to remove from your application.

--secret-id <Secret ID>¶

--id <Secret ID>¶: The ID value of the Secret to remove from your application.

Import Strategies¶

When performing an application import, there are multiple built-in strategies for handling existing entities.

All imports default to the merge strategy unless otherwise specified.

Merge¶

copy

stitch-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. Stitch 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.

Note

If an imported entity has an id field, the value must be an ObjectID or the merge will fail.

Example

An existing application has three functions:

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

A local application directory is imported with the merge strategy.

The directory contains configuration files for the following functions:

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

After importing, the application has the following functions:

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

FunctionA was updated based on its imported configuration file. FunctionB and FunctionC were not included in the imported application directory, so they remained unchanged after importing with the merge strategy. FunctionD was imported as a new entity and assigned a system-generated id value.

Replace¶

copy

stitch-cli import --strategy=replace

Under the replace strategy, if an imported entity’s id value matches the id of an existing entity, Stitch 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, Stitch deletes that existing entity.

Stitch 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.

Example

An existing application has three functions:

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

A local application directory is imported with the replace strategy.

The directory contains configuration files for the following functions:

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

After importing, the application has the following functions:

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

FunctionA was updated based on its imported configuration file. FunctionB and FunctionC were not included in the imported application directory, so they are not present in the app after importing with the replace strategy. FunctionD and FunctionE were imported as new entities and assigned system-generated id values.

Replace by Name¶

copy

stitch-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, Stitch 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, Stitch deletes that existing entity.

If an imported entity has no name value, stitch-cli will throw an error.

Example

An existing application has three functions:

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

A local application directory is imported with the replace strategy.

The directory contains configuration files for the following functions:

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

After importing, the application has the following functions:

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

Both the existing application and the imported configuration directory contained functions with the names FunctionB and FunctionC. As a result, both functions retained their previous id values and names. The rest of both function’s values reflect the values uploaded from the configuration files. FunctionA was not included in the imported application directory, so it is not present in the app after importing with the replace-by-name strategy. FunctionZ was imported as a new entity and assigned a system-generated id value.

← Deploy Changes with Stitch CLI Application Configuration Files →

Stitch CLI¶

Overview¶

Installation¶

Download the stitch-cli binary¶

Add the stitch-cli binary to your system PATH¶

(Linux / macOS) Configure execution permissions for stitch-cli¶

General Options¶

Authentication¶

Authenticate a CLI User¶

Log Out the Current CLI User¶

View the Currently Logged In User¶

Stitch Applications¶

Import an Application¶

Export an Application¶

Diff Pending Application Changes¶

Secrets¶

List All Secrets¶

Create a Secret¶

Update a Secret’s Value¶

Remove a Secret¶

Import Strategies¶

Merge¶

Replace¶

Replace by Name¶

Download the `stitch-cli` binary¶

Add the `stitch-cli` binary to your system PATH¶

(Linux / macOS) Configure execution permissions for `stitch-cli`¶