Extend the Atlas CLI with Custom Plugins

How Plugins Work

Each Atlas CLI plugin consists of two components:

• A manifest.yml file that describes the plugin and its commands

• An executable binary that the Atlas CLI invokes when a user runs a plugin command

When you run a plugin command, the Atlas CLI reads the manifest file, identifies the correct binary, and executes it with the appropriate arguments. The plugin binary handles all command logic independently.

Prerequisites

Before you begin, ensure you have the following installed:

• Go 1.21 or later

• Git

• The Atlas CLI. See Install or Update the Atlas CLI.

Create Your First Plugin

git clone https://github.com/mongodb/atlas-cli-plugin-example.git
cd atlas-cli-plugin-example

atlas-cli-plugin-example/
├── cmd/
│   └── plugin/
│       └── main.go
├── internal/
├── manifest.template.yml
├── go.mod
├── go.sum
├── Makefile
├── .goreleaser.yaml
└── .github/
    └── workflows/
        └── release.yml

name: atlas-cli-plugin-example
description: this is an example plugin
version: $VERSION
github:
    owner: $GITHUB_REPOSITORY_OWNER
    name: $GITHUB_REPOSITORY_NAME
binary: $BINARY
commands:
    example:
        description: Root command of the atlas cli plugin example
        aliases:
            - example-alias-1
            - example-alias-2

package main
import (
    "fmt"
    "os"
    "github.com/spf13/cobra"
)
func main() {
    rootCmd := &cobra.Command{
        Use:   "example",
        Short: "An example Atlas CLI plugin",
        Run: func(cmd *cobra.Command, args []string) {
            fmt.Println("Hello from the Atlas CLI plugin!")
        },
    }
    if err := rootCmd.Execute(); err != nil {
        os.Exit(1)
    }
}

go build -o bin/binary ./cmd/plugin
BINARY=binary VERSION=1.0.0 \
  GITHUB_REPOSITORY_OWNER=$(git remote get-url origin | sed 's/.*[:/]\(.*\)\/.*/\1/') \
  GITHUB_REPOSITORY_NAME=$(basename -s .git $(git remote get-url origin)) \
  envsubst < manifest.template.yml > manifest.yml

PLUGIN_DIR=~/Library/Application\ Support/atlascli/plugins/atlas-cli-plugin-example
mkdir -p "$PLUGIN_DIR"
cp manifest.yml bin/binary "$PLUGIN_DIR/"

PLUGIN_DIR=~/.config/atlascli/plugins/atlas-cli-plugin-example
mkdir -p "$PLUGIN_DIR"
cp manifest.yml bin/binary "$PLUGIN_DIR/"

atlas example

Hello from the Atlas CLI plugin!

Customize Your Plugin

To create your own plugin, modify the example or start from scratch:

1. Update manifest.template.yml with your plugin's name, description, and commands.

2. Implement your command logic in Go (or any language that compiles to a standalone binary).

3. Ensure your binary name matches the binary field in manifest.template.yml.

Distribute Your Plugin

To distribute your plugin so that others can install it with the atlas plugin install command, follow these steps:

1. Host your plugin in a GitHub repository.

2. Use GoReleaser or a similar tool to create GitHub releases with compiled binaries for multiple platforms. The example repository includes a .goreleaser.yaml configuration and a GitHub Actions workflow for automated releases.

3. Create a release tag following semantic versioning (for example, v1.0.0).

After you create a GitHub release, users can install your plugin:

atlas plugin install <github-owner>/<repository-name>

Use a Different Programming Language

While we recommend Go with Cobra, you can write plugins in any language that compiles to a standalone executable binary. For an example of a plugin written in a different language, see the example Rust plugin repository on GitHub.

Your plugin must meet the following requirements:

• Your binary must accept the command name as the first argument.

• Your binary must be a standalone executable (no external runtime dependencies).

• The binary field in manifest.yml must match the binary filename.

Learn More

• atlas plugin - Manage Atlas CLI plugins.

• atlas plugin install - Install a plugin.

• atlas plugin update - Update a plugin.

• atlas plugin uninstall - Uninstall a plugin.

• Atlas CLI plugin example repository

• MongoDB Community Forums