Explore Developer Center's New Chatbot! MongoDB AI Chatbot can be accessed at the top of your navigation to answer all your MongoDB questions.

Learn why MongoDB was selected as a leader in the 2024 Gartner® Magic Quadrant™
MongoDB Developer
Atlas
plus
Sign in to follow topics
MongoDB Developer Center
chevron-right
Developer Topics
chevron-right
Products
chevron-right
Atlas
chevron-right

Extending the MongoDB Atlas CLI With Custom Plugins

Jeroen Vervaeke4 min read • Published Jan 16, 2025 • Updated Jan 16, 2025
Atlas
Facebook Icontwitter iconlinkedin icon
Rate this tutorial
star-empty
star-empty
star-empty
star-empty
star-empty
We're excited to announce a powerful new feature for the MongoDB Atlas Command Line Interface (CLI): plugin support! This addition allows developers to extend the Atlas CLI's functionality using their preferred programming language and tools. This post will explore how plugins work and guide you through creating your first Atlas CLI plugin.
The Atlas CLI plugin system opens up new possibilities for customization and community contributions. Whether you want to add specialized commands for your team's workflow or contribute new features to the broader MongoDB community, plugins make it easier than ever.
What makes this feature particularly exciting is its flexibility. While we provide official support and helper libraries for Go, you can write plugins in any programming language (see a Rust example) that can be compiled into a binary executable. This freedom of choice ensures that developers can contribute to the Atlas CLI ecosystem using tools they're most comfortable with.
Here are some ideas of plugins you could write for the MongoDB Atlas CLI:
  • Automating your company's deployment workflows
  • Enforcing custom security policies
  • Managing environment-specific configurations
  • Implementing team-specific backup strategies
  • Building data lifecycle management tools that align with your business rules
But those are just some ideas—your imagination is the limit!

How plugins work

At its core, an Atlas CLI plugin consists of two essential components: a manifest file and a binary executable. Let's dive into how these work together.

The manifest file

The manifest file (manifest.yml) is the blueprint of your plugin. It defines metadata about your plugin and declares which subcommands it provides. Here's an example:
1name: atlas-cli-plugin-example
2description: this is an example plugin
3version: 2.0.1
4github:
5 owner: mongodb
6 name: atlas-cli-plugin-example
7binary: binary
8commands:
9 example:
10 description: Root command of the atlas cli plugin example
Each field in the manifest serves a specific purpose:
  • name: Your plugin's identifier
  • description: A brief explanation of your plugin's functionality
  • version: The semantic version of your plugin
  • github: Repository information (required for updates)
  • binary: The name of your plugin's executable file
  • commands: The subcommands your plugin provides

Plugin execution

In this section, we'll explain how command execution works in the Atlas CLI plugin system. Understanding this process is crucial for developers as it shows how your plugin interacts with the main CLI application.
When a user runs a plugin command, for example:
1atlas example-plugin do-something --flag value
The Atlas CLI follows a straightforward process:
  1. Locates the plugin's binary
  2. Executes it with the provided arguments: binary do-something --flag value
  3. Pipes stdin, stdout, and stderr between the plugin and the user
This execution model ensures seamless integration between your plugin and the Atlas CLI. From the user's perspective, plugin commands behave like built-in commands, providing a consistent experience throughout the CLI.

Creating your first Atlas CLI plugin

Let's walk through creating a plugin using Go. We'll use Go because it provides access to the official atlas-cli-core helper library, simplifying common tasks like user authentication and Atlas SDK integration.
To make getting started easier, we've created a template repository that includes everything you need to build a plugin. This repository contains several example commands that demonstrate different plugin capabilities. One of these examples is the hello command, which you can try out by installing the example plugin and running atlas example hello—it simply prints "Hello world!"
In this tutorial, we'll use this template as our starting point and modify the hello command to print "Hello world, from my first Atlas CLI plugin!" instead. This will help you understand the basic structure of a plugin and how to make changes to existing functionality.

Prerequisites

  • A GitHub account
  • Go installed on your system
  • An IDE with Go support (recommended)

Step-by-step guide

1. Create your plugin repository

  1. Navigate to GitHub.
  2. Click the "Use this template" button in the top right corner.
  3. Fill in your repository details and create the new repository.
    • Make sure the repository is public. This is needed to install your plugin using atlas install.
  4. Clone your new repository:
1git clone https://github.com/your-github-username/your-repository-name

2. Configure your plugin

Update the manifest.template.yml file with your plugin's information:
1name: blog-example
2description: this is an example plugin
3version: $VERSION
4github:
5 owner: $GITHUB_REPOSITORY_OWNER
6 name: $GITHUB_REPOSITORY_NAME
7binary: binary
8commands:
9 blog-example:
10 description: Root command of the atlas cli plugin example
Note: You don't need to update the $VERSION, $GITHUB_REPOSITORY_OWNER, and $GITHUB_REPOSITORY_NAME placeholders in the GitHub workflow files. These values are automatically populated based on your repository information.
Then, modify cmd/plugin/main.go to update the root command:
1func main() {
2 exampleCmd := &cobra.Command{
3 Use: "blog-example",
4 Short: "Root command of the atlas cli plugin example",
5 }
6 exampleCmd.AddCommand(
7 hello.Builder(),
8 // other commands…
9 )
10 // ... rest of the main function
11}
This changes the root command from example to blog-example, which means we'll now use atlas blog-example hello to execute our command.

3. Implement your plugin logic

Navigate to the internal/cli/hello/hello.go file and update its contents to:
1package hello
2
3import (
4 "fmt"
5
6 "github.com/spf13/cobra"
7)
8
9func Builder() *cobra.Command {
10 return &cobra.Command{
11 Use: "hello",
12 Short: "The Hello World command",
13 Run: func(_ *cobra.Command, _ []string) {
14 fmt.Println("Hello World, from my first AtlasCLI plugin!")
15 },
16 }
17}

4. Commit changes

1git commit -a -m "Blog post changes"
2git push

5. Create a release

1git tag v1.0.0
2git push origin v1.0.0
This will trigger a GitHub action that creates a release with your plugin's binary and manifest. You can monitor the progress of this action by:
  1. Going to your repository on GitHub.
  2. Clicking the "Actions" tab.
Once the action is completed successfully, a new release will be created automatically. You can find this release by:
  1. Going to your repository on GitHub.
  2. Clicking the "Releases" section on the right side.
The release will contain all the necessary files for plugin installation, including the binary for different operating systems and the manifest file.

6. Install your plugin

1atlas plugin install your-github-username/your-repository-name

7. Execute your plugin

1❯ atlas blog-example hello
2
3Hello World, from my first AtlasCLI plugin!

Conclusion

The Atlas CLI plugin allows developers to extend and customize MongoDB's command-line tools to suit their needs best. By providing a flexible framework that supports multiple programming languages and development approaches, we're making it easier for developers to contribute their ideas and solutions to the MongoDB ecosystem.
We're excited to see what plugins you'll create! Whether you're building internal tools for your team or sharing functionality with the broader MongoDB community, the plugin system provides the flexibility and power you need.
Start building your plugin today, and remember to share it with the community!
Top Comments in Forums
There are no comments on this article yet.
Start the Conversation

Facebook Icontwitter iconlinkedin icon
Rate this tutorial
star-empty
star-empty
star-empty
star-empty
star-empty
Related
Quickstart

Building RAG Pipelines With Haystack and MongoDB Atlas


Sep 18, 2024 | 4 min read
Article

Deploying MongoDB Atlas With Terraform with Azure


Jun 18, 2024 | 7 min read
Quickstart

Single Click to Success: Deploying on Netlify, Vercel, Heroku, and Render with Atlas


Apr 10, 2024 | 6 min read
Tutorial

How to Use PyMongo to Connect MongoDB Atlas with AWS Lambda


Apr 02, 2024 | 6 min read
Table of Contents
  • How plugins work