Antwork CLI

La CLI de Antwork es un cliente de línea de comandos para el mismo servidor MCP con el que habla tu asistente de IA. Sirve para cuando prefieres una terminal a una ventana de chat: enviar un borrador desde un archivo, revisar tu cuota antes de un lanzamiento o conectar Antwork a un script que ya tienes.

Estado

Todavía temprano. Hoy funcionan login, whoami, tools y la pasarela directa tool. Los atajos para publicar y programar llegan después. Hasta la versión 1.0 las opciones pueden cambiar.

Lo que no es

• ›No sustituye a la integración con IA: redactar con tu propia voz sigue funcionando mejor desde un asistente que puede leer tu perfil de voz.
• ›No se puede usar en CI ni en cron. Abajo, en Automatización, está el motivo y qué haría falta cambiar.
• ›No es una forma de evitar iniciar sesión. No hay claves de API.

Node 20.9 o superior. El paquete no tiene dependencias en tiempo de ejecución, así que no arrastra nada más.

Todavía no está en npm

Compilar desde el código

git clone https://github.com/iker-gonzalez/antwork.io.git
cd antwork.io && npm ci
npm run cli:build
cd packages/cli && npm link

dist/ no está en el repositorio, así que compila una vez tras clonar. Después, npm link deja un comando antwork real en tu PATH, igual que una instalación publicada.

Cuando se publique

npm install -g antwork

Comprobar

antwork --version

Si antwork no aparece tras instalarlo, tu carpeta global de binarios de npm no está en el PATH. npm prefix -g indica dónde se instaló.

1. Inicia sesión

antwork login

Esto abre tu navegador. Aprueba la solicitud y la terminal continúa sola: no hay ningún código que copiar de vuelta.

2. Comprueba que funcionó

antwork whoami

Deberías ver tu plan, tu espacio de trabajo y cuánta cuota de publicaciones llevas gastada este ciclo.

3. Explora

antwork tools

Todas las herramientas del servidor MCP son accesibles desde la CLI, tengan atajo o no.

Opciones globales: --json para salida procesable por máquinas, además de --version y --help.

Salida y códigos de salida

Los datos van a stdout y todo lo demás a stderr, así que antwork whoami --json | jq siempre funciona. Los códigos de salida forman parte del contrato:

• ›0 — correcto
• ›1 — la operación falló (cuota agotada, cuenta desconectada, id incorrecto)
• ›2 — uso incorrecto (opción desconocida, key=value mal formado)

El servidor expone unas cuarenta herramientas y la CLI solo da atajo a las habituales. antwork tool llega al resto, así que nunca hay nada inaccesible por falta de un subcomando.

antwork tool list_posts status=draft limit=20
antwork tool get_post_context platform=linkedin
antwork tool attach_media post_id=abc123 media_urls=@media.json

Cómo se interpretan los valores

Los valores se interpretan por su forma, no adivinando desde un esquema:

• ›true, false y null se convierten en esos literales.
• ›Los enteros simples se convierten en números, pero solo si la conversión no pierde información: un id como 0123 sigue siendo texto.
• ›Los valores que empiezan por [ o { se interpretan como JSON, y si falla se quedan como texto.
• ›@archivo.json se lee del disco y se interpreta. Úsalo para los argumentos que no encajan en una opción.
• ›Cualquier otra cosa se queda como texto.

Antepón una barra invertida para forzar texto: text=\true y handle=\@antwork.

antwork login usa el flujo OAuth estándar para aplicaciones nativas. La CLI abre un escuchador en tu propio equipo, se registra, te lleva a Antwork en el navegador e intercambia el código devuelto con PKCE. Ninguna contraseña llega a la CLI y no hay nada que copiar y pegar.

Dónde se guardan las credenciales

Se escribe un token de actualización —no una contraseña— en ~/.antwork/credentials.json con permisos 0600.

Trata ese archivo como una contraseña

Cuánto dura la sesión

Los tokens de acceso duran cinco minutos y se renuevan solos. El token de actualización dura treinta días y se renueva cada vez que se usa, así que una CLI que uses cada semana no vuelve a pedirte iniciar sesión. Si la dejas un mes, sí.

En una máquina remota o dentro de un contenedor de desarrollo el navegador se ejecuta en tu portátil, pero la respuesta del inicio de sesión va a la máquina remota, así que el flujo normal no puede terminar. Fija el puerto y redirígelo:

ssh -L 51337:127.0.0.1:51337 your-host
ANTWORK_CALLBACK_PORT=51337 antwork login

Vale cualquier puerto libre, siempre que uses el mismo número en ambos comandos.

La CLI no funciona desatendida, y eso es una característica del servidor, no un olvido aquí.

El servidor de autorización de Antwork solo ofrece los flujos de código de autorización y de actualización. No hay flujo de código de dispositivo, ni credenciales de cliente, ni claves de API, así que todo primer inicio de sesión necesita a una persona con un navegador.

No pongas un token de actualización en CI

«No has iniciado sesión» justo después de iniciar sesión

El archivo de credenciales se escribe al iniciar sesión; si ANTWORK_CREDENTIALS está definida en una terminal y no en otra, cada una ve un archivo distinto. antwork whoami --json indica a qué servidor pertenece el token guardado.

«La sesión ha caducado»

El token de actualización pasó treinta días sin usarse, o se revocó desde los ajustes de IA conectadas. Ejecuta antwork login otra vez.

El navegador se abre pero la terminal no continúa

Hay algo entre el navegador y el escuchador local, normalmente una sesión remota. Mira Iniciar sesión por SSH más arriba.

Una herramienta dice que falta un permiso

Publicar y subir medios necesitan permisos concedidos al iniciar sesión. Si iniciaste sesión antes de que se pidieran, ejecuta antwork login de nuevo para volver a concederlos.

«MCP endpoint not found»

Si has puesto ANTWORK_MCP_URL a mano, quita la barra final. El servidor compara la ruta exacta y una barra de más da un 404 que parece una caída.