Amplíe la interfaz de línea de comandos de Atlas con complementos personalizados.

Cómo funcionan los plugins

Cada complemento de Atlas CLI consta de dos componentes:

• A manifest.yml archivo que describe el complemento y sus comandos

• Un binario ejecutable que la CLI de Atlas invoca cuando un usuario ejecuta un comando de complemento.

Al ejecutar un comando de complemento, la CLI de Atlas lee el archivo de manifiesto, identifica el binario correcto y lo ejecuta con los argumentos apropiados. El binario del complemento gestiona toda la lógica del comando de forma independiente.

Requisitos previos

Antes de comenzar, asegúrese de tener instalado lo siguiente:

• Ir. 1 21 o posterior

• Git

• La interfaz de línea de comandos(CLI) de Atlas. Consulte Instalar o actualizar la CLI de Atlas.

Crea tu primer 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!

Personaliza tu plugin

Para crear tu propio plugin, modifica el ejemplo o empieza desde cero:

1. Actualiza manifest.template.yml con el nombre, la descripción y los comandos de tu plugin.

2. Implementa la lógica de tus comandos en Go (o en cualquier lenguaje que compile a un binario independiente).

3. Asegúrese de que el nombre de su binario coincida con el campo binary en manifest.template.yml.

Distribuye tu plugin

Para distribuir tu plugin de forma que otros puedan instalarlo con el comando atlas plugin install, sigue estos pasos:

1. Aloja tu plugin en un repositorio de GitHub.

2. Utilice GoReleaser o una herramienta similar para crear versiones de GitHub con binarios compilados para múltiples plataformas. El repositorio de ejemplo incluye una .goreleaser.yaml configuración y un flujo de trabajo de GitHub Actions para la automatización de versiones.

3. Cree una etiqueta de lanzamiento siguiendo el versionado semántico (por ejemplo,). v1.0.0

Después de crear una versión en GitHub, los usuarios podrán instalar tu complemento:

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

Utiliza un lenguaje de programación diferente

Aunque recomendamos usar Go con Cobra, puedes escribir complementos en cualquier lenguaje que compile a un binario ejecutable independiente. Para ver un ejemplo de un complemento escrito en otro lenguaje, consulta el repositorio de ejemplos de complementos de Rust en GitHub.

Su complemento debe cumplir los siguientes requisitos:

• Su programa binario debe aceptar el nombre del comando como primer argumento.

• Su archivo binario debe ser un ejecutable independiente (sin dependencias de tiempo de ejecución externas).

• El campo binary en manifest.yml debe coincidir con el nombre del archivo binario.

Obtén más información

• atlas plugin - Manage Atlas CLI plugins.

• atlas plugin install - Install a plugin.

• atlas plugin update - Update a plugin.

• atlas plugin uninstall - Uninstall a plugin.

• Repositorio de ejemplos de complementos de Atlas CLI

• Foros de MongoDB Community