thing

@unravel-tech/thing

CLI para thing: publica, versiona y comparte artefactos (páginas HTML, documentos Markdown, imágenes independientes y PDFs) desde agentes de codificación.

npx -y @unravel-tech/thing push report.html

Ese primer push abre la aprobación en el navegador, espera el inicio de sesión, luego se reanuda e imprime la URL duradera. Markdown, imágenes y PDFs funcionan de la misma manera. Instálalo globalmente si lo usas a menudo: npm i -g @unravel-tech/thing.

Comandos

Comando	Qué hace
thing --version / thing version	Muestra la versión del CLI instalado
thing update [--force] [--manager npm|bun]	Instala la última versión globalmente; --force se ejecuta incluso cuando el servidor reporta esta versión como actual
thing login [--account name] [--server url] [--no-browser]	Añade o actualiza una cuenta nombrada con inicio de sesión por código de dispositivo; por defecto el nombre es el correo autenticado
thing accounts	Lista las cuentas guardadas y muestra a cuál resuelve este directorio
thing switch <account> [--local]	Cambia la cuenta predeterminada global, o vincula una cuenta al repositorio Git/directorio de trabajo actual
thing switch --clear-local	Elimina el vínculo de cuenta heredado por el directorio actual
thing logout [--account name] [--all] / thing whoami	Elimina las credenciales guardadas / muestra la identidad resuelta y dónde aterrizan los pushes
thing default [team] [--clear]	Muestra o establece tu destino de push predeterminado del lado del servidor (usado cuando no se da --team, desde cualquier máquina)
thing setup claude [--remove] [--dry-run]	Permite que el modo automático de Claude Code publique en thing sin rechazos: añade usething.ai y thing push a las entradas de confianza autoMode en ~/.claude/settings.json, manteniendo los valores predeterminados de Claude Code. Ejecútalo tú mismo (en Claude Code escribe ! npx -y @unravel-tech/thing@latest setup claude); --remove lo deshace
thing use <team> [project]	Establece una anulación local de equipo/proyecto activo para esta máquina
thing push <file.html|.md|.pdf|.png|.jpg|.gif|.webp> [--name x] [--team t] [--project p] [--visibility v] [--password p]	Autentica si es necesario, luego publica una nueva versión inmutable e imprime la URL servida. --visibility es private (solo tú y las personas que agregues), team (todos en la organización, el predeterminado) o public (cualquiera con el enlace). --password permite que cualquiera que lo conozca abra el artefacto junto al acceso de equipo y personas
thing list	Lista los artefactos que puedes ver; filtra con --label o --search, ordena con --sort created o updated y --order asc o desc, pagina con --limit y --offset
thing comments <name>	Extrae comentarios y respuestas de un artefacto visible
thing versions <name>	Historial de versiones de un artefacto
thing rollback <name> <n>	Apunta "latest" de vuelta a la versión n
thing open <name>	Abre el artefacto en un navegador
thing mcp	Ejecuta un servidor de Protocolo de Contexto de Modelo (MCP) sobre stdio (herramientas: server_info, push_artifact, list_artifacts, list_artifact_comments, whoami)

Cada comando acepta --json para salida legible por máquina. Los comandos autenticados también aceptan --account name para usar una cuenta guardada una vez sin cambiar ni el predeterminado global ni un vínculo de directorio. Un push --json no autenticado emite el estado de autenticación separado por nuevas líneas; el objeto JSON final es siempre el resultado del push. Usa --no-login para fallar rápido en lugar de iniciar autenticación interactiva, como en CI.

Valores de visibilidad: private, team, anyone-with-link (imprime una URL de compartir con token), public.

Actualizaciones

Thing admite actualizaciones de aviso y obligatorias publicadas por el servidor de Thing. Una actualización de aviso imprime un aviso limitado por frecuencia a stderr pero deja que el comando continúe. Una actualización obligatoria detiene los comandos normales con código de salida 3 mientras mantiene disponibles --help, --version y update. --json devuelve un error estructurado CLIENT_UPDATE_REQUIRED.

El CLI verifica como máximo una vez por hora y muestra el mismo aviso como máximo una vez por día. Establece THING_NO_UPDATE_NOTICES=1 para ocultar los avisos de aviso; las actualizaciones obligatorias no se pueden suprimir. thing update --force reinstala la última versión incluso cuando la versión actual aún es compatible.

Las sesiones MCP exponen la versión instalada a través del apretón de manos de inicialización y la herramienta server_info. Los avisos de actualización aparecen en las instrucciones de MCP, una notificación de registro y el primer resultado de herramienta de negocio. Las actualizaciones obligatorias dejan server_info disponible pero detienen las herramientas de artefactos hasta que Thing se actualice y el cliente MCP se reinicie.

El endpoint correspondiente del servidor de Thing y el middleware de aplicación se especifican en THING_SERVER_UPDATE_POLICY.md.

Resolución de contexto

Cuentas

Thing puede mantener múltiples inicios de sesión en una máquina. Da nombres cortos a las cuentas cuando las agregues, listalas y cambia el predeterminado global:

thing login --account work
thing login --account personal
thing accounts
thing switch work

Para asociar el repositorio actual con una cuenta, ejecuta:

thing switch work --local

Dentro de un repositorio Git, esto vincula su raíz y cada directorio debajo de ella. Fuera de Git, vincula el directorio de trabajo actual y sus descendientes. El vínculo se almacena en tu configuración de usuario—no en .thing.json—para que los nombres de cuenta personales y las credenciales nunca se conviertan en cambios del repositorio. Un vínculo local gana sobre el predeterminado global; --account personal gana sobre ambos para un comando. Usa thing switch --clear-local para eliminar el vínculo.

Los archivos de configuración de inicio de sesión único existentes migran automáticamente a una cuenta llamada default. Los nuevos inicios de sesión sin --account usan la dirección de correo autenticada como nombre de cuenta.

La selección de cuenta se resuelve en este orden: --account → el vínculo más cercano de repositorio/directorio → la selección global thing switch → la única cuenta guardada. THING_TOKEN y THING_SERVER aún anulan las credenciales almacenadas para configuraciones de CI y MCP.

Equipo y proyecto

En qué equipo aterriza un push se decide en orden: bandera --team → .thing.json en el directorio de trabajo → una anulación local thing use → tu predeterminado del lado del servidor (thing default) → tu espacio personal. El inicio de sesión ya no fija un equipo, así que con ninguna de las anulaciones establecidas el servidor elige tu predeterminado (por ejemplo, la organización Unravel para miembros de Unravel).

MCP

Claude Code, Cursor, Codex y cualquier otra cosa que hable Protocolo de Contexto de Modelo pueden publicar a través de thing. No se necesita inicio de sesión en terminal: crea un token en usething.ai en Configuración, luego Tokens, y pega esto en la configuración MCP de tu cliente.

{
  "mcpServers": {
    "thing": {
      "command": "npx",
      "args": ["-y", "@unravel-tech/thing@latest", "mcp"],
      "env": { "THING_TOKEN": "paste-your-token-here" }
    }
  }
}

En una máquina que tiene Bun pero no Node, intercambia npx por bunx:

{
  "mcpServers": {
    "thing": {
      "command": "bunx",
      "args": ["-y", "@unravel-tech/thing@latest", "mcp"],
      "env": { "THING_TOKEN": "paste-your-token-here" }
    }
  }
}

El servidor expone cuatro herramientas: server_info para la versión instalada y el estado de actualización, push_artifact para publicar un archivo o contenido en línea y obtener de vuelta un enlace, list_artifacts para ver lo que tienes, y whoami para verificar a qué cuenta y equipo estás publicando.

Si ya ejecutaste thing login, la credencial almacenada se usa y THING_TOKEN se puede omitir.

Entornos de ejecución

Node >= 18 o Bun, sin dependencias de ejecución. El ejecutable thing se lanza bajo cualquiera de los dos que esté en tu PATH (Node primero), así que una instalación global funciona en una máquina que nunca ha instalado Node:

bun i -g @unravel-tech/thing
thing login