> This page location: /docs.md > /docs/tools-and-connectors.md > /docs/atlas/cli/current.md > /docs/atlas/cli/current/atlas-cli-tutorials.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  other tabs: macos, linux
-->

# Extend the Atlas CLI with Custom Plugins

The Atlas CLI supports plugins that let you extend its functionality with custom commands. You can develop plugins in any programming language that compiles to a standalone binary.

This tutorial walks you through creating your first Atlas CLI plugin using [Go](https://go.dev/) and the [Cobra](https://github.com/spf13/cobra) library.

To learn more about installing and managing existing plugins, see [atlas plugin.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-plugin.md#std-label-atlas-plugin)

## 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](https://go.dev/dl/) 1.21 or later

- [Git](https://git-scm.com/downloads)

- The Atlas CLI. See [Install or Update the Atlas CLI.](https://www.mongodb.com/docs/atlas/cli/current/install-atlas-cli.md#std-label-install-atlas-cli)

## Create Your First Plugin

1. Clone the example plugin repository.

   MongoDB provides an example plugin repository that you can use as a starting point:

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

2. Explore the project structure.

   The example plugin has the following structure:

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

3. Review the manifest file.

   Open `manifest.template.yml` to see the plugin configuration:

   ```yaml
   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
   ```

   `manifest.template.yml` defines the manifest file for the plugin. The manifest tells the Atlas CLI which commands the plugin provides and which binary to execute.

4. Review the plugin code.

   Open `cmd/plugin/main.go` to see the plugin implementation:

   ```go
   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)
       }
   }
   ```

   The plugin uses [Cobra](https://github.com/spf13/cobra) to define commands. When the Atlas CLI runs the plugin, it passes the command name and arguments to the binary.

5. Build and install the plugin.

   From the root of the repository, build the plugin binary and generate the manifest file:

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

   Create the plugin directory and copy the files. The default plugin directory depends on your operating system:

   ### macOS

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

6. Run the plugin command.

   Verify that the plugin works:

   ```bash
   atlas example
   ```

   The output resembles the following:

   ```none
   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`.

**Important:**

Command names in your manifest must not conflict with existing Atlas CLI commands or commands from other installed plugins.

## 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](https://goreleaser.com/) 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](https://semver.org/) (for example, `v1.0.0`).

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

```bash
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](https://github.com/mongodb-developer/atlas-cli-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](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-plugin.md#std-label-atlas-plugin) - Manage Atlas CLI plugins.

- [atlas plugin install](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-plugin-install.md#std-label-atlas-plugin-install) - Install a plugin.

- [atlas plugin update](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-plugin-update.md#std-label-atlas-plugin-update) - Update a plugin.

- [atlas plugin uninstall](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-plugin-uninstall.md#std-label-atlas-plugin-uninstall) - Uninstall a plugin.

- [Atlas CLI plugin example repository](https://github.com/mongodb/atlas-cli-plugin-example)

- [MongoDB Community Forums](https://www.mongodb.com/community/forums/)
