thing

@unravel-tech/thing

CLI para thing: envie, versione e compartilhe artefatos (páginas HTML, documentos Markdown, imagens independentes e PDFs) a partir de agentes de codificação.

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

Esse primeiro envio abre a aprovação no navegador, aguarda o login e, em seguida, retoma e imprime a URL durável. Markdown, imagens e PDFs funcionam da mesma forma. Instale globalmente se você usa com frequência: npm i -g @unravel-tech/thing.

Comandos

Comando	O que faz
thing --version / thing version	Mostra a versão da CLI instalada
thing update [--force] [--manager npm|bun]	Instala a versão mais recente globalmente; --force executa mesmo quando o servidor informa esta versão como atual
thing login [--server url] [--no-browser]	Login explícito com código de dispositivo; abre aprovação no navegador e armazena um token
thing logout / thing whoami	Limpa / mostra a identidade atual e para onde os envios vão
thing default [team] [--clear]	Mostra ou define seu destino de envio padrão no servidor (usado quando nenhum --team é fornecido, de qualquer máquina)
thing use <team> [project]	Define uma substituição local de equipe/projeto ativo para esta máquina
thing push <file.html|.md|.pdf|.png|.jpg|.gif|.webp> [--name x] [--team t] [--project p] [--visibility v]	Autentica se necessário, envia uma nova versão imutável e imprime a URL servida
thing list	Lista artefatos que você pode ver
thing versions <name>	Histórico de versões de um artefato
thing rollback <name> <n>	Aponta o "latest" de volta para a versão n
thing open <name>	Abre o artefato em um navegador
thing mcp	Executa um servidor Model Context Protocol via stdio (ferramentas: server_info, push_artifact, list_artifacts, whoami)

Todo comando aceita --json para saída legível por máquina. Um push --json não autenticado emite o status de autenticação separado por novas linhas; o objeto JSON final é sempre o resultado do envio. Use --no-login para falhar rapidamente em vez de iniciar autenticação interativa, como em CI.

Valores de visibilidade: private, team, anyone-with-link (imprime uma URL de compartilhamento com token), public.

Atualizações

O Thing suporta atualizações consultivas e obrigatórias publicadas pelo servidor Thing. Uma atualização consultiva imprime um aviso com limite de frequência no stderr, mas permite que o comando continue. Uma atualização obrigatória interrompe comandos normais com código de saída 3, mantendo --help, --version e update disponíveis. --json retorna um erro estruturado CLIENT_UPDATE_REQUIRED.

A CLI verifica no máximo uma vez por hora e mostra o mesmo aviso consultivo no máximo uma vez por dia. Defina THING_NO_UPDATE_NOTICES=1 para ocultar avisos consultivos; atualizações obrigatórias não podem ser suprimidas. thing update --force reinstala a versão mais recente mesmo quando a versão atual ainda é suportada.

Sessões MCP expõem a versão instalada por meio do handshake de inicialização e da ferramenta server_info. Atualizações consultivas aparecem nas instruções MCP, em uma notificação de log e no primeiro resultado de ferramenta de negócios. Atualizações obrigatórias deixam server_info disponível, mas interrompem as ferramentas de artefato até que o Thing seja atualizado e o cliente MCP seja reiniciado.

O endpoint correspondente do servidor Thing e o middleware de aplicação são especificados em THING_SERVER_UPDATE_POLICY.md.

Resolução de contexto

Em qual equipe um envio cai é decidido nesta ordem: flag --team → .thing.json no diretório de trabalho → uma substituição local thing use → seu padrão no servidor (thing default) → seu espaço pessoal. O login não fixa mais uma equipe, então, sem nenhuma das substituições definidas, o servidor escolhe seu padrão (por exemplo, a organização Unravel para membros da Unravel).

MCP

Claude Code, Cursor, Codex e qualquer outra coisa que fale Model Context Protocol pode publicar via thing. Sem necessidade de login no terminal: crie um token em usething.ai em Configurações, depois Tokens, e cole isto na configuração MCP do seu cliente.

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

Em uma máquina que tem Bun, mas não Node, troque npx por bunx:

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

O servidor expõe quatro ferramentas: server_info para a versão instalada e status de atualização, push_artifact para publicar um arquivo ou conteúdo inline e obter de volta um link, list_artifacts para ver o que você tem, e whoami para verificar em qual conta e equipe você está enviando.

Se você já executou thing login, a credencial armazenada é usada e THING_TOKEN pode ser omitido.

Runtimes

Node >= 18 ou Bun, sem dependências de runtime. O executável thing inicia sob qualquer um dos dois que estiver no seu PATH (Node primeiro), então uma instalação global funciona em uma máquina que nunca instalou Node:

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