El Notion CLI: qué es, por qué importa y cómo usarlo desde la terminal

Notion se ha consolidado como una de las plataformas más utilizadas para organizar trabajo, conocimiento y proyectos, tanto en equipos como de forma individual. En muchos flujos profesionales y académicos, la interacción cotidiana ocurre sobre todo en la interfaz web o en las aplicaciones oficiales. Sin embargo, cuando el objetivo es automatizar, repetir operaciones con precisión o conectar Notion con herramientas de desarrollo y despliegue, cobra relevancia un canal distinto: la línea de comandos, lo que en informática se resume como una CLI (Command-Line Interface): instrucciones de texto que ejecutas en una terminal. Pero, ¿qué es exactamente el Notion CLI y por qué resulta tan importante para quienes quieren aprovechar Notion más allá de la navegación manual?

En el Centro de ayuda de Notion la herramienta se presenta como la CLI de Notion (ntn): una interfaz de línea de comandos para leer y actualizar Notion escribiendo comandos, pensada sobre todo para desarrolladores y asistentes de programación con IA. La configuración técnica detallada vive en la documentación para desarrolladores. En este artículo unimos ambos niveles: conceptos, buenas prácticas y ejemplos prácticos en español.

En este artículo, desglosaremos qué es una CLI (por si el término es nuevo para ti), qué es el Notion CLI (ntn), cómo instalarlo y autenticarlo según la documentación actual, cómo obtener credenciales (incluido lo que mucha gente busca como «notion api key»), cómo localizar IDs, comandos esenciales basados en ntn y escenarios de automatización para proyectos de software y de estudio. Si quieres reducir fricción entre tu terminal y tu espacio de trabajo, comprender esta herramienta es un paso esencial.

¿Qué es una CLI?

CLI son las siglas en inglés de Command-Line Interface; en español suele traducirse como interfaz de línea de comandos. En la práctica es un modo de usar un programa escribiendo instrucciones de texto en una ventana llamada terminal, consola o símbolo del sistema, en lugar de (o además de) hacer clic en iconos y menús en una interfaz gráfica.

Tú escribes una orden (por ejemplo, el nombre de un comando y algunos parámetros), pulsas Enter, y el programa interpreta esa línea, hace el trabajo y te responde con texto en la misma ventana: una lista, un mensaje de confirmación, un error con detalle, etc. Ese ciclo se puede repetir, guardar en un script y combinar con otros programas; por eso las CLIs son tan habituales en desarrollo, servidores y automatización.

Si alguna vez ejecutaste algo como node -v, git status o winget install … en una ventana negra o azul, ya usaste una CLI: solo faltaba el nombre. La CLI de Notion (ntn) es otro programa más que se suma a esa idea: entiende comandos propios (como ntn login o ntn api …) y los traduce en operaciones sobre tu espacio de trabajo en Notion. No sustituye por completo la experiencia en el navegador o en la app, pero te da un canal preciso y repetible cuando quieres scriptear, integrar o trabajar desde la terminal.

Cómo leer esta guía según tu perfil

El mismo flujo base sirve para perfiles técnicos y académicos; lo que cambia es el “segundo paso” que más te conviene practicar primero.

Si desarrollas software: prioriza instalación reproducible, autenticación con NOTION_API_TOKEN en CI, la sección de seguridad, IDs desde URLs, solución de problemas y la guía ntn api / Workers cuando toque.
Si estudias (secundaria, universidad o por tu cuenta): prioriza instalar ntn, ejecutar ntn login en tu cuenta, confirmar en la app que puedes abrir las páginas o bases que quieres usar, y practicar ntn doctor y un primer ntn api o ntn pages get sobre una página de prueba. Luego copia una receta del final y adáptala.

Regla de oro (alineada con la ayuda oficial): si no puedes abrir la página o la base de datos en Notion con tu usuario, la CLI tampoco podrá leerla ni modificarla. Primero comprueba el acceso en la app; después automatiza.

Entendiendo el Notion CLI y su contexto

Según la descripción general del CLI, ntn es el Notion CLI: sirve para autenticarte en Notion, desplegar y gestionar Notion Workers, y realizar peticiones a la API desde la terminal. El propio ejecutable y los paquetes npm se llaman ntn (no confundir con búsquedas antiguas que mencionan el comando notion u otros paquetes legacy).

Imagina que Notion es un tablero flexible y visualmente rico, útil para pensar, documentar y colaborar. El CLI, en cambio, es el canal por el que se expresan instrucciones repetibles, versionables y fáciles de encadenar en scripts. De manera similar a como una instrucción clara orienta a un modelo de inteligencia artificial hacia un resultado útil, un comando bien formulado orienta a Notion hacia una acción concreta y auditable.

Desde un punto de vista técnico, el CLI actúa como puente entre la API de Notion y tu entorno local (terminal, repositorios, CI). Eso lo convierte en un recurso valioso para desarrolladores y para perfiles académicos que quieren repetir tareas sin tanto clic manual.

Beneficios clave de usar el Notion CLI

Integrar el Notion CLI (ntn) suele ser una decisión de diseño de flujo de trabajo: reduce trabajo manual repetido y hace más predecible la forma en que consultas o actualizas datos.

Automatización y scripting: scripts que consulten páginas, adjunten archivos o disparen flujos vía API, encadenados con otras herramientas.
Inspección y depuración: ntn api permite probar cuerpos de petición y ver respuestas sin montar un cliente HTTP aparte (guía de API requests).
Workers: crear, desplegar y operar Workers desde la terminal (referencia de comandos).
Archivos: subir activos con ntn files create y enlazarlos a bloques o propiedades según la guía de subidas.
Bases como tablas (data sources): consultar y gestionar fuentes de datos con ntn datasources y la API (guía de data sources).

Lo que conviene tener presente (según el Centro de ayuda)

La CLI es opcional y está pensada sobre todo para flujos de trabajo de desarrollo (ayuda en español).

La CLI está disponible en todos los planes; implementar y gestionar Workers puede requerir plan Business o Enterprise y permisos del administrador del espacio.

Si algo falla, lo primero suele ser actualizar ntn a la última versión y comprobar cuenta, acceso en la app y permisos de Workers si usas esos comandos.

Primeros pasos con el Notion CLI: Instalación

La instalación recomendada en la documentación oficial usa el script:

curl -fsSL https://ntn.dev | bash

y la verificación:

ntn --version

Importante: en la misma página de instalación se indica que ntn está disponible para macOS y Linux (x64 y arm64) y que el soporte para Windows con este script llegará próximamente (Windows support coming soon). En la práctica, en Windows suele ser más fiable usar npm (o WSL si quieres el script curl | bash en un entorno Linux).

Requisitos si instalas con npm

La vía npm oficial es:

npm install --global ntn

La documentación indica que esta ruta requiere Node.js 22+ y npm 10+ (no basta con “16 o superior”). Comprueba versiones:

node -v
npm -v

¿No tienes Node.js instalado o la terminal no reconoce el comando?

En Windows: con winget:
```
winget install OpenJS.NodeJS.LTS
```
Asegúrate de que la versión instalada sea 22 o superior (si el LTS aún no cumple en tu máquina, instala una versión Current 22+ desde nodejs.org). Si winget no está disponible, usa el instalador desde https://nodejs.org/.
En macOS: instala Node.js 22+ desde nodejs.org, con Homebrew (brew install node si ya trae 22+), o con nvm / fnm (nvm install 22).

Tras instalar, cierra y vuelve a abrir la terminal y ejecuta de nuevo node -v, npm -v y ntn --version.

Completaciones de shell (opcional)

La documentación de instalación incluye:

ntn completions bash   # o fish, zsh, powershell, elvish

Autenticando el Notion CLI (`ntn`)

La fuente de verdad es la guía de autenticación.

Inicio de sesión interactivo (`ntn login`)

ntn login

Se abre el navegador para autorizar el acceso; comprueba que el código en el navegador coincide con el de la terminal antes de aprobar. Las credenciales se guardan de forma segura en el llavero del sistema (keychain). Si ya tienes varios espacios, puedes elegir el espacio por defecto o autenticar uno nuevo.

Nota oficial: ntn login requiere ser miembro completo del espacio de trabajo; invitados (guests) y miembros restringidos no pueden usar el inicio de sesión del CLI. Si necesitas acceso, pide a un administrador que actualice tu rol. Detalles en la propia página de autenticación.

Sin navegador: `ntn login poll` o PAT

En máquinas sin navegador, ntn login puede usar un flujo en dos pasos (URL + código de verificación + ntn login poll); las sesiones caducan pronto.

Para uso desatendido (CI, bots, scripts), la documentación recomienda un personal access token (PAT). Expórtalo como NOTION_API_TOKEN (tiene precedencia sobre la sesión del llavero):

export NOTION_API_TOKEN="ntn_xxx..."
ntn api v1/users/me

En Windows (PowerShell), sesión actual:

$env:NOTION_API_TOKEN = "ntn_xxx..."
ntn api v1/users/me

En GitHub Actions u otros CI, define el mismo valor como secreto del repositorio (por ejemplo NOTION_API_TOKEN) y mapea env: NOTION_API_TOKEN: ${{ secrets.NOTION_API_TOKEN }}.

Inspección y cierre de sesión

Diagnóstico: ntn doctor (referencia).
Cerrar sesión y borrar credenciales en llavero: ntn logout.

Otras variables útiles documentadas: NOTION_WORKSPACE_ID, NOTION_KEYRING=0 (almacenamiento en archivo en entornos sin llavero; tratar auth.json como secreto), NOTION_HOME. Ver tabla en Authentication.

«Notion api key»: qué buscan la gente y qué usar en la práctica

Muchas búsquedas dicen “notion api key” o “Notion API key”. En la terminología actual de la plataforma para desarrolladores, lo que necesitas para el CLI en CI o scripts suele ser un personal access token (PAT):

Crea un PAT siguiendo la guía oficial: Personal access tokens.
El token suele verse como una cadena que empieza por ntn_.
Expórtalo como NOTION_API_TOKEN en tu shell o en el secreto del pipeline (no lo pegues en el repositorio).

Así cubres la intención de búsqueda (api key) sin mezclarlo con flujos antiguos basados en otros nombres de variable o paquetes.

Cómo obtener el ID de una página o de una base de datos

Los comandos ntn api y los subcomandos de páginas/datasources usan identificadores de la API. En la práctica se obtienen desde la URL al abrir la página o la base en el navegador (también se explica en el contexto de data sources enlazando a Working with databases).

Copia el identificador de 32 caracteres (a veces con guiones en la URL).
Para bases con varias fuentes de datos, la guía recomienda ntn api v1/databases/<database-id> y el array data_sources, o copiar el data source ID desde Notion: menú de la base → Manage data sources → menú ••• → Copy data source ID.

Seguridad: tokens, repositorios y equipos

Un PAT o una sesión de ntn login otorgan acceso real a tu espacio de trabajo: trátalos como contraseñas.

No los subas a Git: usa .env en .gitignore y un .env.example sin secretos.
CI/CD: solo secretos del proveedor; nunca imprimas tokens en logs.
Rotación: revoca y crea un PAT nuevo si sospechas filtración.

Comandos principales (resumen alineado con la referencia oficial)

La lista completa está en la referencia de comandos. Resumen útil:

Ayuda y diagnóstico

ntn --help / ntn <subcomando> --help
ntn doctor, comprobar auth, llavero, red y configuración.

Peticiones a la API

ntn api <ruta>, ver API requests. Ejemplos de la documentación:
- ntn api v1/pages/$PAGE_ID
- Cuerpos inline con sintaxis tipo HTTPie (path=value, path:=json, consultas con ==).
ntn api ls, listar superficie de la API; con --json para scripts.

Páginas (Markdown)

Según la referencia: ntn pages get, ntn pages create, ntn pages update (crear/actualizar contenido desde Markdown; ver flags --parent, --content, etc. en la referencia).

Archivos

ntn files create < ./archivo.pdf, subida por stdin; --plain, --json para scripts (guía).
Los archivos subidos hay que adjuntarlos a una página o propiedad con ntn api en la ventana de tiempo indicada en la guía (evitar que expire el upload).

Data sources

ntn datasources resolve <database-id>, obtener IDs de fuentes de datos.
ntn datasources query <data-source-id> --filter '<json>', consultas con paginación (--start-cursor, etc.) (guía).

Workers

Comandos ntn workers … (nuevo, desplegar, listar, entorno, OAuth, runs, webhooks). Requisitos de plan y permisos según Centro de ayuda.

Solución de problemas frecuentes

Orden sugerido por la ayuda en español:

Actualiza ntn (ntn update o reinstala con npm) y vuelve a probar.
Comprueba la cuenta y el espacio de trabajo correctos (ntn logout / ntn login si hace falta).
Comprueba el acceso en la app antes de culpar al CLI.
Si usas Workers, verifica que estén habilitados y que tu plan y rol lo permitan.
Para errores concretos de un comando, revisa la documentación para desarrolladores enlazada al mensaje de error.

Otros casos frecuentes:

command not found: ntn: revisa PATH tras npm install -g ntn y reinicia la terminal.
Llavero / contenedor / SSH: revisa NOTION_KEYRING=0 y las advertencias de seguridad en Authentication.
Filtros en datasources query: el JSON debe cumplir el esquema de Filter data source entries y los nombres de propiedad deben coincidir.

Casos de uso avanzados y automatización

Aquí el CLI aporta más valor cuando forma parte de scripts y hábitos repetibles: Workers, ntn api, subidas de archivos y consultas a data sources.

Ideas de alto impacto para estudiantes

El Quick Capture: tu bandeja de entrada en la terminal

Antes de automatizar, conviene saber cómo se identifica una página para la API: el error más frecuente es pegar la URL entera; la terminal solo necesita el ID de la página (un identificador de 32 caracteres que Notion asocia a esa nota).

¿Cómo obtener tu Page ID real a partir de la URL?

Si tu cuaderno abre una URL como esta:

https://www.notion.so/Derecho-aplicado-a-la-informatica-360b7f9a49cc801088b4f3d911317cf1

Slug (para humanos): Derecho-aplicado-a-la-informatica-, es el fragmento legible en el enlace; no es lo que debes pasar a ntn api.
ID real (para la API): 360b7f9a49cc801088b4f3d911317cf1, son los 32 caracteres hexadecimales del final; eso es el valor que usarás como PAGE_ID.

Nota técnica: si la URL incluye ? (por ejemplo …?v=…), todo lo que va después de ? son parámetros del navegador, no parte del ID. Copia solo el bloque de 32 caracteres que queda inmediatamente antes del ?.

El flujo en pocos minutos

Imagina que estás estudiando o programando y te surge una duda para clase: en lugar de abrir el navegador y perder el hilo, escribes en la terminal:

ntn_note "Preguntar al profesor sobre la complejidad O(n log n) de este algoritmo"

y la línea queda en tu Notion al instante (necesitas ntn login hecho al menos una vez en esa máquina, o NOTION_API_TOKEN exportado).

Paso 1, Prepara la página

Crea en Notion una página llamada, por ejemplo, “Inbox académico”, y copia su ID de 32 caracteres siguiendo la regla de arriba.

Paso 2, Añade la función en tu shell

En Bash (Linux, WSL o Git Bash en Windows) edita ~/.bashrc; en Zsh (muy habitual en macOS) suele ser ~/.zshrc. Pega al final del archivo y sustituye el valor de PAGE_ID por el tuyo:

# Captura rápida a Notion vía CLI (requiere ntn en PATH y sesión / token configurados)
ntn_note() {
  local PAGE_ID="TU_ID_DE_32_CARACTERES_AQUI"
  local TEXT="$1"

  if [ -z "$TEXT" ]; then
    echo "Uso: ntn_note 'Contenido de tu nota'"
    return 1
  fi

  echo "Enviando a Notion…"

  ntn api "v1/blocks/${PAGE_ID}/children" -X PATCH \
    children[0][type]=paragraph \
    children[0][paragraph][rich_text][0][text][content]="> [$(date +'%H:%M')] ${TEXT}" >/dev/null

  echo "Listo: nota añadida al inbox."
}

# En Bash el nombre de función no puede llevar guion; usa un alias si prefieres escribir ntn-note:
alias ntn-note=ntn_note

Evita comillas dobles dentro del texto de la nota (o escápalas), para no romper la línea que construye el cuerpo de la petición.

Paso 3, Recarga la configuración y prueba

source ~/.bashrc   # o: source ~/.zshrc
ntn_note "Revisar fallos en la arquitectura del TP de ingeniería"
# equivalente, gracias al alias:
ntn-note "Revisar fallos en la arquitectura del TP de ingeniería"

Abre Notion: deberías ver un párrafo nuevo con prefijo tipo cita > [hh:mm] y tu texto.

¿Por qué vale la pena? El coste más alto al estudiar suele ser el cambio de contexto (navegador, pestañas, notificaciones). Si ya vives en la terminal, ntn te permite capturar sin salir de ahí y seguir organizando después con vistas y bases en Notion.

Otros patrones útiles con el CLI:

PDFs: ntn files create y adjuntar con ntn api (guía de archivos).
Prioridades: ntn datasources query con --filter según tu esquema (guía de data sources).

Ideas orientadas a desarrollo y operaciones

Pipelines que ejecuten ntn api o scripts que envuelvan ntn.
CI/CD (referencia rápida): en GitHub Actions suele bastar runs-on: ubuntu-latest, Node 22+, npm install --global ntn, un secreto NOTION_API_TOKEN y un paso como ntn api v1/users/me para validar credenciales antes de tu script real.
Workers: ntn workers new, ntn workers deploy, etc. (Workers overview).

Recetas de arranque rápido (Bash)

Asumen Bash (Linux, macOS, WSL o Git Bash). Sustituye los IDs por los tuyos. Para captura rápida en una página, la opción más completa es la función ntn_note de la sección Quick Capture anterior.

1) Subir un PDF y adjuntarlo como bloque de archivo en una página

Patrón de la guía de file uploads: primero files create, luego PATCH a v1/blocks/.../children.
PAGE_ID="tu_page_id"
FILE="./lectura.pdf"
FILE_UPLOAD_ID=$(ntn files create --plain < "$FILE" | cut -f1)
ntn api "v1/blocks/${PAGE_ID}/children" -X PATCH \
  children[0][type]=file \
  children[0][file][type]=file_upload \
  children[0][file][file_upload][id]="$FILE_UPLOAD_ID" \
  children[0][file][name]="$(basename "$FILE")"
2) Consultar tareas urgentes no hechas en un data source

Obtén el data_source_id con ntn datasources resolve <database-id> y luego consulta con el mismo formato de filtro que en la guía (ajusta nombres y valores a tu base):
DATA_SOURCE_ID="tu_data_source_id"
ntn datasources query "$DATA_SOURCE_ID" \
  --filter '{"and":[{"property":"Priority","select":{"equals":"High"}},{"property":"Status","status":{"does_not_equal":"Done"}}]}'

La Plataforma para Desarrolladores de Notion: contexto

El CLI (ntn) forma parte de la Plataforma para desarrolladores de Notion, junto con Workers, agentes y documentación pública. Los requisitos de plan y permisos dependen de cada función; la ayuda en español enlaza a la documentación técnica cuando hace falta ir al detalle.

Conclusión

El Notion CLI (ntn) es una herramienta potente para quien ya trabaja desde la terminal o desde pipelines: autenticación clara (ntn login o NOTION_API_TOKEN), acceso a la API con ntn api, gestión de archivos y data sources, y Workers cuando tu organización y plan lo permiten. Empieza por instalación actualizada, ntn doctor y una sola petición de prueba (ntn api v1/users/me o ntn pages get sobre una página que ya abras en la app); después añade scripts y CI con secretos bien guardados.

¿Qué hacer ahora? Reserva unos 30 minutos: instala ntn (Node 22+ si usas npm), ejecuta ntn login o configura NOTION_API_TOKEN, corre ntn doctor y una consulta mínima a la API. Si eres estudiante, configura el inbox con ntn_note de la sección Quick Capture; si no, elige otra automatización pequeña (un PDF repetible o una consulta de estudio) y déjala en un script versionado sin secretos en el repo.