MongoDB Atlas CLI: gestiona bases de datos desde la línea de comandos

MongoDB Atlas es un servicio de base de datos en la nube que te permite desplegar, gestionar y escalar bases de datos MongoDB. Puedes administrar Atlas desde la Atlas UI, una interfaz web, o con Atlas CLI, una herramienta de línea de comandos con la que realizar las mismas tareas mediante comandos.

MongoDB Atlas CLI es una alternativa más rápida a la Atlas UI. Puedes ejecutar y automatizar tareas de administración de bases de datos directamente desde tu terminal.

En este artículo, te guiaré paso a paso para usar Atlas CLI y gestionar tus bases de datos.

Requisitos previos

Antes de empezar, asegúrate de tener:

• Una cuenta de MongoDB Atlas.
• Conocimientos básicos de la línea de comandos.
• Requisitos de instalación de Atlas CLI para tu sistema operativo.

Estructura de los comandos de la CLI

MongoDB Atlas CLI sigue una estructura de comandos consistente:

atlas [command] [subcommand] [flags]

Cuando ejecutas un comando sin subcomandos ni flags, la CLI muestra información de ayuda que incluye:

• Uso: cómo utilizar el comando.
• Alias: nombres alternativos del comando.
• Comandos disponibles: subcomandos que puedes ejecutar.
• Flags: opciones específicas del comando.
• Flags globales: opciones disponibles en todos los comandos de la CLI.

Por ejemplo, si ejecutas:

atlas clusters

Obtendrás una respuesta similar a esta:

Manage clusters for your project. The clusters command provides access to your cluster configurations. You can create, edit, and delete clusters.

Usage:
  atlas clusters [command]

Aliases:
  clusters, cluster

Available Commands:
  list              Return all clusters for your project.
  describe          Return the details for the specified cluster for your project.
  advancedSettings  Manage advanced configuration settings for your cluster.
 ...

Flags:
  -h, --help   help for clusters

Global Flags:
  -P, --profile string   Name of the profile to use from your configuration file. To learn about profiles for the Atlas CLI, see https://dochub.mongodb.org/core/atlas-cli-save-connection-settings.

Use "atlas clusters [command] --help" for more information about a command.

Los nombres de comandos, argumentos y flags en Atlas CLI distinguen entre mayúsculas y minúsculas. Usa exactamente las mayúsculas indicadas en los ejemplos: por ejemplo, --orgId, no --orgID.

Crear un despliegue de MongoDB

Un despliegue es una instancia en ejecución de MongoDB que almacena y sirve tus datos. Cada despliegue incluye los servidores de base de datos, almacenamiento, red y copias de seguridad automatizadas. MongoDB Atlas se encarga de la infraestructura para que puedas centrarte en usar la base de datos en lugar de mantener servidores.

Para crear un despliegue de MongoDB, instala o actualiza Atlas CLI y ejecuta el comando:

atlas setup

El comando atlas setup te guía por un proceso interactivo. Te pedirá elecciones de configuración y creará un proyecto, aprovisionará un clúster y configurará los ajustes básicos de seguridad.

Autenticarse con un despliegue existente

Si ya tienes un despliegue de MongoDB Atlas y quieres gestionarlo con la CLI, necesitas autenticarte. Para iniciar sesión, ejecuta:

atlas auth login

Este comando te pide que selecciones el tipo de autenticación y luego te proporciona un código de verificación de un solo uso. Cópialo y pégalo en el navegador cuando se te solicite. Por ejemplo:

atlas auth login
? Select authentication type: UserAccount

To verify your account, copy your one-time verification code:
QPWF-6GT4

Paste the code in the browser when prompted to activate your Atlas CLI. Your code will expire after 3 minutes.

To continue, go to https://account.mongodb.com/account/connect

Press Enter to open the browser and complete authentication...
Successfully logged in as your-email@example.com.

Después de autenticarte, elegirás una organización y un formato de salida por defecto. La CLI guarda tu sesión, pero caduca periódicamente. Cuando veas un error de "session expired", ejecuta de nuevo atlas auth login.

Gestionar perfiles para múltiples entornos

Los perfiles te permiten gestionar varios entornos de MongoDB Atlas desde la misma instalación de la CLI. Cada perfil guarda la configuración de conexión de un entorno diferente, como desarrollo, preproducción o producción.

Con perfiles, puedes cambiar de entorno rápidamente sin volver a autenticarte ni modificar archivos de configuración. Es útil cuando mantienes proyectos u organizaciones de MongoDB Atlas separados para cada fase de tu flujo de desarrollo.

Una práctica habitual es crear proyectos de Atlas separados para cada entorno y gestionarlos con perfiles. Por ejemplo:

• Perfil de desarrollo: apunta a tu proyecto de dev con un clúster M0 pequeño para pruebas.
• Perfil de staging: apunta a tu proyecto de preproducción que replica la configuración de producción.
• Perfil de producción: apunta a tu proyecto de producción con clústeres de nivel productivo.

Crear perfiles para distintos entornos

La primera vez que ejecutas atlas auth login, la CLI crea un perfil por defecto. Para crear perfiles adicionales para otros entornos, usa el flag --profile:

atlas auth login --profile dev

Esto crea un perfil llamado "dev" y te guía por el proceso de autenticación. Repite para cada entorno:

atlas auth login --profile staging
atlas auth login --profile production

Cada perfil almacena sus propias credenciales de autenticación, proyecto por defecto y ajustes de organización.

Listar perfiles disponibles

Para ver todos los perfiles configurados, ejecuta:

atlas config list

Verás todos los nombres de perfil que hayas creado.

Ver detalles de un perfil

Para ver la configuración de un perfil concreto, ejecuta:

atlas config describe <profileName>

Por ejemplo:

atlas config describe dev

Se mostrarán los ajustes del perfil, incluida la organización y los ID de proyecto por defecto.

Cambiar entre perfiles

Para usar un perfil concreto en un comando, añade el flag --profile:

atlas clusters list --profile production

Esto lista los clústeres usando las credenciales y la configuración del perfil de producción.

También puedes establecer un perfil por defecto para no tener que indicarlo en cada comando:

atlas config set --profile staging

Tras fijar un perfil por defecto, todos los comandos usarán ese perfil salvo que lo sobreescribas con el flag --profile.

Actualizar la configuración de un perfil

Para modificar la configuración de un perfil, ejecuta:

atlas config set <setting> <value> --profile <profileName>

Por ejemplo, para establecer un proyecto por defecto en el perfil dev:

atlas config set project_id 5f8e8d9a1b2c3d4e5f6g7h8i --profile dev

Renombrar perfiles

Para cambiar el nombre de un perfil, ejecuta:

atlas config rename <oldName> <newName>

Por ejemplo:

atlas config rename dev development

Gestionar proyectos

Los proyectos en MongoDB Atlas organizan tus clústeres, usuarios y ajustes. Piensa en un proyecto como un contenedor que agrupa recursos de base de datos relacionados.

Cada proyecto puede contener varios clústeres y tiene su propio conjunto de usuarios y controles de acceso. Esta separación es útil cuando diferentes aplicaciones, entornos o equipos necesitan recursos de base de datos aislados.

Crear proyectos

Para crear un proyecto nuevo, ejecuta:

atlas projects create <projectName> [options]

Usa un nombre descriptivo que refleje su propósito, como "ecommerce-transactions" o "mobile-app-staging".

[options] incluye flags que modifican cómo y dónde se crea el proyecto. Por ejemplo, puedes indicar la organización en la que crearlo:

atlas projects create mobile-app-staging --orgId <organizationId>

El flag --orgId especifica la organización en la que crear el proyecto. Es obligatorio salvo que tengas una organización por defecto configurada. Puedes ejecutar atlas organizations list para obtener la lista de tus organizaciones y su Id.

En todos los ejemplos, sustituye marcadores como <projectId>, <clusterName> y <username> por tus nombres e identificadores reales de proyecto, clúster o usuario.

Actualizar proyectos

Para actualizar la configuración de un proyecto, usa:

atlas projects update <projectId> [options]

Por ejemplo, puedes usar el flag --name para cambiar el nombre del proyecto:

atlas projects update <projectId> --name newProjectName

Listar proyectos

Para listar todos los proyectos de tu organización, usa:

atlas projects list [options]

El comando anterior usa el flag --orgId como opción para indicar de qué organización listar los proyectos:

atlas projects list --orgId <organizationId>

También puedes controlar el formato de salida, por ejemplo, mostrar los resultados en JSON:

atlas projects list --output json

Eliminar proyectos

Puedes eliminar un proyecto con un comando de Atlas CLI.

atlas projects delete <projectId> --orgId <organizationId>

No puedes borrar un proyecto que aún tenga clústeres activos. Antes de eliminar un proyecto, asegúrate de borrar todos los clústeres que contiene.

Gestionar clústeres

Los clústeres son grupos de servidores MongoDB que almacenan tus datos. Atlas gestiona la infraestructura, la replicación y las copias de seguridad de tus clústeres.

Crear clústeres

Para crear un clúster nuevo, ejecuta:

atlas clusters create <clusterName> [options]

[options] incluye flags que definen la configuración del clúster. Por ejemplo, puedes añadir opciones para indicar el proveedor cloud, la región y el nivel de precios de MongoDB:

atlas clusters create myCluster --provider AWS --region US_EAST_1 --tier M0

En este comando, el flag --provider especifica el proveedor cloud, como AWS, GCP o Azure. El flag --region indica la región donde se desplegará el clúster. El flag --tier define el tamaño del clúster.

Si no has establecido un proyecto por defecto, incluye el flag --projectId:

atlas clusters create myCluster --projectId <projectId> --provider AWS --region US_EAST_1 --tier M0

Describir clústeres

Para ver los detalles de un clúster concreto, ejecuta:

atlas clusters describe <clusterName> --projectId <projectId>

Este comando muestra la configuración del clúster, tamaño, región y cadenas de conexión.

Listar clústeres

Para listar todos los clústeres de tu proyecto, ejecuta:

atlas clusters list --projectId <projectId>

El flag --projectId es obligatorio salvo que hayas establecido un proyecto por defecto con:

atlas config set project_id <projectId>

Pausar clústeres

Puedes pausar temporalmente un clúster sin eliminarlo. Esto detiene sus operaciones pero conserva tus datos y configuración:

atlas clusters pause <clusterName> --projectId <projectId>

Eliminar clústeres

Para eliminar un clúster de forma permanente, ejecuta:

atlas clusters delete <clusterName> --projectId <projectId>

Después de crear tu clúster, debes configurar la seguridad de red antes de poder conectarte.

Gestionar la configuración de la lista de acceso IP

Una lista de acceso IP controla qué direcciones IP pueden conectarse a tus clústeres de MongoDB Atlas. Cada proyecto puede tener hasta 200 entradas en su lista de acceso. Puedes añadir direcciones IP individuales, rangos en notación CIDR o IDs de grupos de seguridad de AWS. Un rango en notación CIDR define un bloque de direcciones IP usando una IP base y un prefijo—por ejemplo, 192.168.0.0/24. Un ID de grupo de seguridad de AWS permite el acceso desde todos los recursos dentro de ese grupo de seguridad.

Para gestionar listas de acceso IP debes tener acceso de Project Owner en el proyecto.

Añadir direcciones IP a la lista de acceso

Para añadir tu IP actual a la lista de acceso, ejecuta:

atlas accessLists create --currentIp --projectId <projectId>

El flag --currentIp añade automáticamente la IP de la máquina desde la que ejecutas el comando. Es útil para dar acceso rápido desde tu equipo de desarrollo.

Para añadir una IP concreta, ejecuta:

atlas accessLists create <ipAddress> --type ipAddress --projectId <projectId>

<ipAddress> es la IP a la que quieres permitir acceso. Por ejemplo:

atlas accessLists create 192.0.2.15 --type ipAddress --comment "Office network" --projectId <projectId>

El flag --comment añade una descripción para ayudarte a identificar la entrada más adelante.

Para añadir un rango de IPs usando notación CIDR, ejecuta:

atlas accessLists create <cidrBlock> --type cidrBlock --projectId <projectId>

Por ejemplo:

atlas accessLists create 73.231.201.0/24 --type cidrBlock --comment "Development servers" --projectId <projectId>

Crear entradas temporales en la lista de acceso

Para añadir una IP que caduque automáticamente tras un tiempo, usa el flag --deleteAfter. Puedes fijar fechas de caducidad hasta siete días en el futuro:

atlas accessLists create <ipAddress> --type ipAddress --deleteAfter <isoDateTime> --projectId <projectId>

El flag --deleteAfter acepta una fecha en formato ISO-8601. Por ejemplo:

atlas accessLists create 192.0.2.20 --type ipAddress --deleteAfter 2025-12-31T23:59:59Z --comment "Temporary contractor access" --projectId <projectId>

MongoDB Atlas elimina la entrada automáticamente en la fecha y hora indicadas.

Listar entradas de la lista de acceso IP

Para ver todas las entradas de la lista de acceso IP de tu proyecto, ejecuta:

atlas accessLists list --projectId <projectId>

Para ver los detalles de una entrada concreta, ejecuta:

atlas accessLists describe <entry> --projectId <projectId>

<entry> puede ser la dirección IP, el bloque CIDR o el ID del grupo de seguridad de AWS que quieres consultar.

Eliminar entradas de la lista de acceso IP

Para eliminar una IP de la lista de acceso, ejecuta:

atlas accessLists delete <entry> --projectId <projectId>

Gestionar usuarios y roles

Un rol concede privilegios para realizar conjuntos de acciones sobre recursos específicos. Un usuario es una entidad a la que se le asignan uno o varios roles que determinan a qué puede acceder en la base de datos.

Para configurar usuarios y roles de base de datos, debes tener acceso de Organization Owner, Project Owner o Project Database Access Admin en MongoDB Atlas.

Gestionar usuarios

Para crear un usuario de base de datos, ejecuta:

atlas dbusers create [builtInRole] [options]

[builtInRole] es uno o varios roles integrados que asignar al usuario. [options] incluye flags que especifican las credenciales y configuración del usuario. Por ejemplo:

atlas dbusers create --username myUser --password myPassword --role readWriteAnyDatabase --projectId <projectId>

El flag --username indica el nombre de usuario. El flag --password establece la contraseña. El flag --role define el rol a asignar. En este caso, el usuario es myUser y la contraseña myPassword.

Para listar todos los usuarios de base de datos de tu proyecto, ejecuta:

atlas dbusers list --projectId <projectId>

Para ver los detalles de un usuario concreto, ejecuta:

atlas dbusers describe <username> --projectId <projectId>

También puedes actualizar el usuario. Por ejemplo, para cambiar su contraseña, ejecuta:

atlas dbusers update myUser --password newPassword --projectId <projectId>

Para actualizar los roles de un usuario, ejecuta:

atlas dbusers update myUser --role readWriteAnyDatabase --role dbAdmin --projectId <projectId>

Para eliminar un usuario de base de datos, ejecuta:

atlas dbusers delete <username> --projectId <projectId>

Gestionar roles

Hay dos categorías de roles que puedes asignar a un usuario:

• Roles integrados
• Roles personalizados

Roles integrados

Los roles integrados son roles predefinidos que ofrece MongoDB Atlas. Incluyen conjuntos de permisos comunes para distintos casos de uso, como:

• read: concede acceso de solo lectura a una base de datos específica.
• readWrite: permite leer y modificar datos en una base de datos concreta.
• readAnyDatabase: concede acceso de solo lectura a todas las bases de datos excepto local y config.
• readWriteAnyDatabase: concede lectura y escritura en todas las bases de datos.
• dbAdmin: proporciona privilegios administrativos para una base de datos específica, como crear índices o ver estadísticas.
• dbAdminAnyDatabase: concede privilegios administrativos en todas las bases de datos.
• clusterAdmin: te permite administrar todo el clúster, incluida la replicación y el sharding.
• userAdminAnyDatabase: te permite crear y modificar cuentas de usuario y roles en todas las bases de datos.

No puedes editar ni eliminar los roles integrados; solo asignarlos a usuarios. Para asignarlos al crear usuarios, indica el rol con el flag --role:

atlas dbusers create --username app-reader --password myPassword --role readAnyDatabase --projectId <projectId>

Para asignar o cambiar el rol de un usuario existente, ejecuta:

atlas dbusers update app-reader --role readWriteAnyDatabase --projectId <projectId>

Consulta [Built-In Roles and Privileges](https://www.mongodb.com/docs/atlas/mongodb-users-roles-and-privileges/?utm_campaign=devrel&utm_source=third-party-content&utm_medium=cta&utm_content=atlas-cli-datacamp&utm_term=megan.grant) para ver más roles integrados que puedes asignar.

Roles personalizados

MongoDB Atlas te permite crear roles personalizados cuando los integrados no cubren tus necesidades. Un rol personalizado define un conjunto de acciones de privilegio específicas que se ajustan a los requisitos de tu aplicación o equipo.

Al crear un rol personalizado, decide a qué colecciones deben acceder los usuarios y qué acciones sobre los recursos podrán realizar—por ejemplo, leer, insertar, actualizar o eliminar datos.

En las definiciones de privilegios de MongoDB debes usar el nombre de la acción en mayúsculas en tu comando de la CLI, como FIND, no find. Consulta Privilege Actions para ver más acciones de privilegio definidas que un usuario puede realizar sobre un recurso.

Puedes gestionar roles personalizados con Atlas CLI.

Para crear un rol personalizado, ejecuta:

atlas customDbRoles create <roleName> [options]

<roleName> es el nombre del rol personalizado que quieres crear. [options] incluye flags que especifican los permisos del rol. Por ejemplo:

atlas customDbRoles create customAnalyticsRole --privilege FIND@myDatabase.users

En el comando anterior:

• customAnalyticsRole es el nombre del nuevo rol personalizado. Elige un nombre descriptivo que refleje su propósito.
• El flag --privilege especifica qué acciones sobre recursos puede realizar el rol.
• El formato es action@database.collection, donde @ separa la acción del recurso.
• FIND es una acción de privilegio reconocida por MongoDB.
• myDatabase.users es el recurso al que aplica el privilegio—en este caso, la colección users en la base de datos myDatabase.

Para ver los detalles de un rol personalizado, ejecuta:

atlas customDbRoles list --projectId <projectId>

El comando anterior muestra todos los roles personalizados y sus permisos.

Para actualizar un rol personalizado, ejecuta:

atlas customDbRoles update <roleName> [options]

[options] incluye flags que especifican qué actualizar. Por ejemplo, para añadir un nuevo privilegio a un rol existente, ejecuta:

atlas customDbRoles update customAnalyticsRole --privilege FIND@myDatabase.analytics --privilege INSERT@myDatabase.logs --projectId <projectId>

El comando anterior actualiza el customAnalyticsRole existente para conceder privilegios adicionales. FIND@myDatabase.analytics permite leer documentos de la colección analytics, e INSERT@myDatabase.logs permite añadir documentos a la colección logs de la base de datos myDatabase.

El flag --projectId indica a qué proyecto de MongoDB Atlas pertenece el rol.

Para eliminar un rol personalizado, ejecuta:

atlas customDbRoles delete <roleName> --projectId <projectId>

Asignar un rol personalizado a un usuario es similar a asignar uno integrado. Usa el flag --role con atlas dbusers create o atlas dbusers update:

atlas dbusers create --username analytics-user --password myPassword --role customAnalyticsRole --projectId <projectId>

Tras crear usuarios de base de datos y asignar roles, ya puedes conectarte a tu clúster.

Obtener cadenas de conexión

Una cadena de conexión contiene la información que tus aplicaciones necesitan para conectarse a tu clúster de Atlas. Incluye el hostname del clúster, la base de datos de autenticación y opciones de conexión.

Antes de usar una cadena de conexión, asegúrate de haber configurado tu lista de acceso IP y creado al menos un usuario de base de datos.

Obtener la cadena de conexión de un clúster

Para recuperar la cadena de conexión de un clúster, ejecuta:

atlas clusters connectionStrings describe <clusterName> --projectId <projectId>

Este comando devuelve la cadena de conexión SRV de tu clúster.

Formatos de cadena de conexión

MongoDB Atlas ofrece dos tipos de cadenas de conexión:

Cadena de conexión estándar (mongodb://): lista explícitamente todos los nodos del clúster. Úsala cuando necesites especificar direcciones de servidor individuales.

Cadena de conexión SRV (mongodb+srv://): utiliza DNS para obtener la información del clúster automáticamente. Es el formato recomendado porque se actualiza solo si cambia la configuración de tu clúster.

Usar la cadena de conexión

Sustituye <username> y <password> en la cadena por las credenciales de tu usuario de base de datos:

mongodb+srv://<username>:<password>@cluster0.example.mongodb.net/

Por ejemplo, si tu usuario es appUser y la contraseña securePass123:

mongodb+srv://appUser:securePass123@cluster0.example.mongodb.net/

Luego puedes usar esta cadena de conexión con los MongoDB Drivers, la MongoDB Shell u otras herramientas de MongoDB para conectarte a tu clúster.

Gestionar copias de seguridad

Las copias de seguridad son duplicados de tus datos que puedes usar para restaurar tu clúster si se pierden o corrompen. Atlas crea copias automáticamente con una programación regular.

Las copias de seguridad continuas automatizadas solo están disponibles para clústeres dedicados M10 o superiores. Los clústeres M0 (nivel gratuito) no tienen copias de seguridad. Los clústeres compartidos M2/M5 disponen de copias básicas en la nube, pero no de copia continua. Para más información, consulta [Snapshots for Flex Clusters](https://www.mongodb.com/docs/atlas/backup-restore-cluster/?utm_campaign=devrel&utm_source=third-party-content&utm_medium=cta&utm_content=atlas-cli-datacamp&utm_term=megan.grant#snapshots-for-flex-clusters).

Para gestionar copias de seguridad debes tener acceso de Organization Owner o Project Owner en Atlas.

Crear copias bajo demanda

Para crear una copia inmediata, ejecuta:

atlas backups snapshots create <clusterName> --desc "Backup description" --projectId <projectId>

En el comando anterior, --desc es un flag obligatorio que describe el snapshot.

Listar copias disponibles

Para listar todas las copias de un clúster, ejecuta:

atlas backups snapshots list <clusterName> --projectId <projectId>

Describir configuraciones de copia

Para ver la configuración de copias de un clúster, ejecuta:

atlas backups schedule describe <clusterName> --projectId <projectId>

Restaurar desde copias

Para restaurar datos desde una copia, ejecuta:

atlas backups restores start <clusterName> --snapshotId <snapshotId> --targetClusterName <targetClusterName> --projectId <projectId>

El flag --snapshotId indica qué copia restaurar. El flag --targetClusterName indica el nombre del clúster donde se restaurarán los datos. Por ejemplo:

atlas backups restores start myCluster --snapshotId 5f8e8d9a1b2c3d4e5f6g7h8i --targetClusterName myCluster-restored --projectId <projectId>

Eliminar copias

Para eliminar una copia, ejecuta:

atlas backups snapshots delete <snapshotId> --projectId <projectId>

Conclusión

En este artículo has visto la estructura de los comandos de la CLI, cómo crear despliegues, gestionar proyectos y clústeres, configurar usuarios y roles, y administrar copias de seguridad. Puedes automatizar estas operaciones combinándolas en scripts, lo que facilita gestionar múltiples entornos e integrar la administración de bases de datos en tu flujo de desarrollo.