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 que esta versão é a atual
thing login [--account name] [--server url] [--no-browser]	Adiciona ou atualiza uma conta nomeada com login por código de dispositivo; o nome padrão é o e-mail autenticado
thing accounts	Lista as contas salvas e mostra qual delas este diretório resolve
thing switch <account> [--local]	Altera o padrão global da conta ou vincula uma conta ao repositório Git/diretório de trabalho atual
thing switch --clear-local	Remove o vínculo de conta herdado pelo diretório atual
thing logout [--account name] [--all] / thing whoami	Remove as credenciais salvas / mostra a identidade resolvida 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 setup claude [--remove] [--dry-run]	Permite que o modo automático do Claude Code publique no thing sem recusas: adiciona usething.ai e thing push às entradas de confiança do autoMode em ~/.claude/settings.json, mantendo os padrões do Claude Code. Execute você mesmo (no Claude Code, digite ! npx -y @unravel-tech/thing@latest setup claude); --remove desfaz
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] [--password p]	Autentica se necessário e, em seguida, envia uma nova versão imutável e imprime a URL servida. --visibility é private (somente você e as pessoas que você adicionar), team (todos na organização, o padrão) ou public (qualquer pessoa com o link). --password permite que qualquer pessoa que o conheça abra o artefato além do acesso de equipe e pessoas
thing list	Lista os artefatos que você pode ver; filtre com --label ou --search, ordene com --sort created ou updated e --order asc ou desc, pagine com --limit e --offset
thing comments <name>	Puxa comentários e respostas de um artefato visível
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, list_artifact_comments, whoami)

Todo comando aceita --json para saída legível por máquina. Comandos autenticados também aceitam --account name para usar uma conta salva uma única vez sem alterar o padrão global ou um vínculo de diretório. 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 a 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 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

Contas

O Thing pode manter vários logins em uma única máquina. Dê nomes curtos às contas quando você as adicionar, liste-as e alterne o padrão global:

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

Para associar o repositório atual a uma conta, execute:

thing switch work --local

Dentro de um repositório Git, isso vincula sua raiz e todos os diretórios abaixo dela. Fora do Git, vincula o diretório de trabalho atual e seus descendentes. O vínculo é armazenado na sua configuração de usuário—não em .thing.json—para que nomes de conta pessoais e credenciais nunca se tornem alterações no repositório. Um vínculo local tem prioridade sobre o padrão global; --account personal tem prioridade sobre ambos para um único comando. Use thing switch --clear-local para remover o vínculo.

Arquivos de configuração existentes de login único migram automaticamente para uma conta chamada default. Novos logins sem --account usam o endereço de e-mail autenticado como nome da conta.

A seleção de conta é resolvida nesta ordem: --account → o vínculo mais próximo de repositório/diretório → a seleção global thing switch → a única conta salva. THING_TOKEN e THING_SERVER ainda substituem as credenciais armazenadas para configurações de CI e MCP.

Equipe e projeto

Em qual equipe um envio é publicado é 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 podem publicar por meio do 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 tenha 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 é iniciado 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