Notion desde el terminal: la CLI oficial y cuándo no usarla

Guía interna de IAcademy. Acompaña al módulo M23 · Notion CLI y productividad.

La respuesta corta

Notion publicó su propia CLI en mayo de 2026, junto con su plataforma para desarrolladores. Se llama ntn y hace tres cosas: autenticarte contra tu espacio, desplegar Workers y lanzar peticiones a la API desde el terminal. Si buscabas «hay que usar herramientas de terceros», esa parte ya no es cierta: lo oficial existe y es lo primero que conviene probar.

Ponerla en marcha

curl -fsSL https://ntn.dev | bash   # instala
ntn --version                        # comprueba
ntn login                            # abre el navegador y autoriza

El inicio de sesión abre una ventana del navegador y guarda las credenciales en el llavero del sistema. Es cómodo para trabajar delante del ordenador y es, a la vez, su límite: si el proceso tiene que correr solo, sin nadie delante, esta no es la vía (ni la CLI ni el MCP, que también va por OAuth con navegador). Para eso, token de integración y API directa.

Lo que hace, con ejemplos reales

Workers

ntn workers new      # crea el esqueleto del proyecto
ntn workers deploy   # construye y sube
ntn workers list     # lista lo desplegado

Los Workers son programas pequeños en TypeScript —sincronizaciones, herramientas y webhooks— que se ejecutan en la infraestructura de Notion, sin servidor propio. Se despliegan con la CLI, pero requieren plan Business o Enterprise: la CLI es de todos los planes, los Workers no.

Peticiones a la API

ntn api v1/users                                  # GET
ntn api v1/pages parent[page_id]=abc123           # POST con cuerpo en línea
ntn api v1/pages/abc123 -X PATCH archived:=true   # PATCH con asignación tipada

Construir el cuerpo en línea, con autocompletado de shell, evita el ida y vuelta de copiar el JSON a otra herramienta. Para depurar una integración, es la forma más rápida de ver qué devuelve la API.

Ficheros y fuentes de datos

ntn files create < foto.png                        # sube un fichero local
ntn files create --external-url https://…/foto.png # o desde una URL
ntn files list

Además, crea, consulta y gestiona fuentes de datos desde el terminal. Ahí es donde la CLI se vuelve útil de verdad para el trabajo diario: consultar sin abrir la interfaz.

Los cuatro caminos, sin mitos

VíaAutenticaciónCuándo
ntn, CLI oficialntn login (navegador)Trabajo manual y de agente con una persona delante; Workers; depurar la API
API oficialToken de integración, OAuth o personalProcesos desatendidos, control fino de bloques, ficheros y consultas
Servidor MCP oficialOAuth (alojado)Que un agente lea y escriba en lenguaje natural, contigo delante
Plataformas (n8n, Make, Zapier)Credencial del conectorProcesos de empresa con reintentos, aprobaciones y registro

Las CLI de terceros siguen existiendo y algunas funcionan bien, pero ya no son la única forma ni la primera que recomendar: empieza por la oficial y baja a la de la comunidad solo si te falta algo concreto.

El modelo de datos, que es lo que ahorra horas

Antes de automatizar, decide qué es una base y qué es una vista: una base por dominio (proyectos, personas, decisiones) y las vistas como perspectivas sobre la misma información. Si creas una base por vista tendrás cinco sitios donde actualizar lo mismo, y ninguna CLI te salva de eso. La automatización multiplica la estructura que ya tienes; no la ordena por ti.

Errores que se pagan caros

Lo que cambió en 2026, en una línea

Webhooks y operaciones por lotes: los primeros acaban con el sondeo para detectar cambios; las segundas reducen a una fracción las escrituras masivas. Son las dos piezas que hacen que automatizar Notion deje de ser un ejercicio de paciencia.

Seguir