MongoDB

Jeroen Vervaeke

Senior Software Engineer

We're excited to announce a powerful new feature for the MongoDB Atlas Command Line Interface (CLI): [plugin support](https://github.com/mongodb/atlas-cli-plugin-example/blob/master/README.md)! 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](https://github.com/mongodb-developer/atlas-cli-rust-plugin)) 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:

```
name: atlas-cli-plugin-example
description: this is an example plugin
version: 2.0.1
github:
    owner: mongodb
    name: atlas-cli-plugin-example
binary: binary
commands: 
    example: 
        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:

```bash
atlas 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](https://github.com/mongodb/atlas-cli-plugin-example).  
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:

```bash
git 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:

```yaml
name: blog-example
description: this is an example plugin
version: $VERSION
github:
  owner: $GITHUB_REPOSITORY_OWNER
  name: $GITHUB_REPOSITORY_NAME
binary: binary
commands:
  blog-example:
    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:

```go
func main() {
    exampleCmd := &cobra.Command{
        Use:   "blog-example",
        Short: "Root command of the atlas cli plugin example",
    }
    exampleCmd.AddCommand(
        hello.Builder(),
        // other commands…
    )
    // ... rest of the main function
}
```

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:

```go
package hello

import (
	"fmt"

	"github.com/spf13/cobra"
)

func Builder() *cobra.Command {
	return &cobra.Command{
		Use:   "hello",
		Short: "The Hello World command",
		Run: func(_ *cobra.Command, _ []string) {
			fmt.Println("Hello World, from my first AtlasCLI plugin!")
		},
	}
}
```

#### 4. Commit changes

```bash
git commit -a -m "Blog post changes"
git push
```

#### 5. Create a release

```bash
git tag v1.0.0
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:
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

```bash
atlas plugin install your-github-username/your-repository-name
```

#### 7.  Execute your plugin

```bash
❯ atlas blog-example hello

Hello 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](https://www.mongodb.com/community/forums/)!


Learn how to create custom plugins for the MongoDB Atlas CLI using any programming language. Follow our step-by-step guide to extend CLI functionality and streamline your MongoDB workflows.

Jeroen Vervaeke

Conteúdo de Jeroen Vervaeke

Estendendo o MongoDB Atlas CLI com plug-ins personalizados