Extending the MongoDB Atlas CLI With Custom Plugins
Rate this tutorial
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!
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 (
manifest.yml
) is the blueprint of your plugin. It defines metadata about your plugin and declares which subcommands it provides. Here's an example:1 name: atlas-cli-plugin-example 2 description: this is an example plugin 3 version: 2.0.1 4 github: 5 owner: mongodb 6 name: atlas-cli-plugin-example 7 binary: binary 8 commands: 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 identifierdescription
: A brief explanation of your plugin's functionalityversion
: The semantic version of your plugingithub
: Repository information (required for updates)binary
: The name of your plugin's executable filecommands
: The subcommands your plugin provides
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:
1 atlas example-plugin do-something --flag value
The Atlas CLI follows a straightforward process:
- Locates the plugin's binary
- Executes it with the provided arguments:
binary do-something --flag value
- 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.
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.
- A GitHub account
- Go installed on your system
- An IDE with Go support (recommended)
- Click the "Use this template" button in the top right corner.
- 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
.
- Clone your new repository:
1 git clone https://github.com/your-github-username/your-repository-name
Update the
manifest.template.yml
file with your plugin's information:1 name: blog-example 2 description: this is an example plugin 3 version: $VERSION 4 github: 5 owner: $GITHUB_REPOSITORY_OWNER 6 name: $GITHUB_REPOSITORY_NAME 7 binary: binary 8 commands: 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:1 func 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.Navigate to the
internal/cli/hello/hello.go
file and update its contents to:1 package hello 2 3 import ( 4 "fmt" 5 6 "github.com/spf13/cobra" 7 ) 8 9 func 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 }
1 git commit -a -m "Blog post changes" 2 git push
1 git tag v1.0.0 2 git 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:
- Going to your repository on GitHub.
- Clicking the "Actions" tab.
Once the action is completed successfully, a new release will be created automatically. You can find this release by:
- Going to your repository on GitHub.
- 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.
1 atlas plugin install your-github-username/your-repository-name
1 ❯ atlas blog-example hello 2 3 Hello World, from my first AtlasCLI plugin!
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.
Top Comments in Forums
There are no comments on this article yet.