CLI

O comando puxadinho faz no terminal tudo o que o agente faz pelo MCP: criar boxes, rodar comandos, trocar arquivos e publicar portas

Instalar e entrar

Instale
Terminal
```
$ npm i -g puxadinho
```
Precisa do Node 24 ou mais novo. Funciona no macOS e no Linux. Para usar uma vez sem instalar: npx puxadinho@latest.
Aponte para o puxadinho
Terminal
```
$ export PUXADINHO_API_URL=https://www.usepuxadinho.com.br
```
Ponha a linha no seu ~/.zshrc ou ~/.bashrc para valer sempre.
Entre
Terminal
```
$ puxadinho login
```
A CLI mostra um código e abre o navegador. Confira o código, entre e libere. Depois, puxadinho whoami mostra quem está conectado.

Primeiros comandos

Terminal

$ puxadinho create --name teste$ puxadinho exec teste -- uname -a$ puxadinho ls$ puxadinho rm teste# ou tudo de uma vez: cria, roda, traz o resultado e apaga$ puxadinho run --push . --pull out -- npm run build

Na dúvida, puxadinho --help ou puxadinho COMANDO --help.

Opções de todos os comandos

Opção	O que faz
`--api-url string`	URL da API (ou PUXADINHO_API_URL)
`--json`	saída em JSON (automático quando a saída não é um terminal)
`--no-wait`	não espera operações longas terminarem
`--org string`	workspace (envia Puxadinho-Org)
`PUXADINHO_API_URL`	URL da API (o mesmo que --api-url).
`PUXADINHO_API_KEY`	Usa esta chave de API no lugar do login salvo. Nunca é gravada em disco.

Códigos de saída

Úteis em scripts e para o agente saber o que deu errado.

Código	Quer dizer
0	Deu certo
1	Falha geral
2	Uso errado (flag ou argumento)
3	Autenticação ou permissão
4	Não encontrado
5	Limite ou plano (gasto, cota, tamanho)
6	A box não ficou pronta a tempo
75	Falha passageira, tente de novo
125	Falha do puxadinho run (não do seu comando)

exec e run saem com o código do seu próprio comando.

Todos os comandos

Conta e agentes

puxadinho login

Entra na sua conta (código de dispositivo) ou cadastra um agente

Sem flags, mostra um código, abre o navegador e espera você aprovar. Com --agent, cria um pedido de cadastro: você (ou seu humano) aprova o link /claim?code=XXXX-XXXX ou roda "puxadinho claim XXXX-XXXX" em outro terminal.

--agent: cadastra um agente (Claude Code, Codex…) em vez de uma pessoa
--client string: claude_code, codex ou other (com --agent; detecta pelo ambiente)
--expires-in-days int: validade da chave do agente em dias, 1 a 365 (com --agent)
--name string: nome do agente (com --agent)
--no-browser: só imprime o link, sem abrir o navegador
--scope strings: escopo pedido pelo agente (repetível; com --agent)

puxadinho logout

Sai da conta e apaga as credenciais locais

puxadinho whoami

Mostra quem está autenticado e os workspaces

puxadinho claim XXXX-XXXX

Aprova o pedido de um agente pelo terminal

--scope strings: restringe os escopos pedidos pelo agente (repetível)

puxadinho keys

Gerencia as chaves de API do workspace

puxadinho keys create

Cria uma chave (o valor aparece só agora)

--expires-in-days int: validade em dias, 1 a 365 (padrão: não expira)
--name string: nome da chave (obrigatório)
--scope strings: escopo (repetível; padrão boxes:read, boxes:write, boxes:exec)

puxadinho keys ls

Lista as chaves · também: list

puxadinho keys rm KEY_ID

Revoga uma chave · também: revoke

puxadinho setup

Prepara o Claude Code ou o Codex para usar o puxadinho (MCP e skill)

puxadinho setup claude

Faz login se preciso, registra o MCP e instala a skill no Claude Code

puxadinho setup codex

Faz login se preciso, registra o MCP e instala a skill no Codex

puxadinho mcp

MCP do puxadinho (servidor local e registro nos agentes)

puxadinho mcp init [claude|codex]

Só registra o MCP hospedado no Claude Code ou no Codex (sem skill)

puxadinho mcp start

Servidor MCP local por stdio, com as mesmas tools do /mcp hospedado

Fala MCP por stdin/stdout e repassa cada tool à API do puxadinho com a credencial da CLI. Use como comando de um agente: "puxadinho mcp start".

puxadinho update

Atualiza a CLI para a última versão (npm i -g puxadinho@latest)

--check: só verifica, sem instalar

puxadinho feedback "<texto>"

Envia um feedback para a equipe do puxadinho

--box string: id da box relacionada
--kind string: bug, idea ou other (default "other")

Boxes

puxadinho create

Cria uma box e espera ela ficar pronta

--auto-suspend string: pausa por ociosidade: off ou de 5m a 30m
--data-gib int: tamanho do /data em GiB (20 a 500)
--delete-after string: apaga sozinha depois deste prazo (ex.: 2h)
--max-run string: limite de tempo rodando: minutos, 0 (pausa já) ou unlimited (sem limite)
--mem-mib int: memória em MiB (2048 × vCPUs)
--metadata stringArray: metadado chave=valor (repetível)
--name string: nome da box (único no workspace; sem isso o servidor gera um)
--secret stringArray: nome de um Secret do workspace (repetível)
--setup-file string: script que roda depois do boot
--snapshot string: cria a partir de um snapshot (snp_…)
--template string: template: padrao ou midia
--vcpus int: vCPUs: 2, 4, 8, 16 ou 32

puxadinho ls

Lista as boxes · também: list

--all: inclui boxes apagadas nos últimos 30 dias
--metadata stringArray: filtra por metadado chave=valor (repetível)
--state strings: filtra por estado, ex.: running, suspended (repetível)

puxadinho get BOX

Mostra uma box (id ou nome)

puxadinho rm BOX

Apaga uma box (sem volta) · também: delete

-y, --yes: não pergunta antes de apagar

puxadinho start BOX

Liga uma box desligada

puxadinho stop BOX

Desliga a box (só volta com start)

puxadinho suspend BOX

Pausa a box (só volta com resume)

puxadinho resume BOX

Retoma uma box pausada

puxadinho restart BOX

Reinicia a box

puxadinho wake BOX

Acorda uma box pausada por ociosidade ou max-run

puxadinho fork BOX

Copia a box em até 5 (as cópias sobem a frio)

--count int: número de cópias, de 1 a 5 (default 1)
--name stringArray: nome de uma cópia (repetível; sem isso, <nome>-1, <nome>-2…)

puxadinho resize BOX

Muda o tamanho da box (vale no próximo boot)

--data-gib int: tamanho do /data em GiB (só cresce)
--mem-mib int: memória em MiB (2048 × vCPUs)
--vcpus int: vCPUs: 2, 4, 8, 16 ou 32

puxadinho auto-suspend BOX <10m|off>

Define em quanto tempo ocioso a box pausa (off, ou de 5m a 30m)

puxadinho max-run BOX <minutos|unlimited>

Define por quanto tempo seguido a box pode rodar

Minutos (a box pausa depois disso), 0 (pausa já) ou unlimited (-1, sem limite).

puxadinho logs BOX

Mostra o console de boot e as últimas operações

--lines int: linhas do console (1 a 5000) (default 200)

puxadinho wait OPERATION_ID

Espera uma operação terminar

Espera uma operação (op_…) terminar. Falha com o código da operação; create_timeout sai com 6.

--timeout duration: prazo máximo de espera (0 = sem prazo) (default 15m0s)

puxadinho usage

Mostra o uso e o custo do mês (R$)

--period string: mês AAAA-MM (padrão: o mês corrente)

Comandos na box

puxadinho exec BOX [--cwd DIR] [--env K=V]... [--timeout 600] -- COMANDO...

Roda um comando na box e mostra a saída ao vivo

Roda um comando na box. Um argumento só é interpretado por "bash -lc"; vários são executados direto. A saída vem ao vivo e a CLI sai com o código do comando (sinal → 128+n; tempo esgotado → 124). Com --json, espera o fim e imprime o ExecResult.

--cwd string: pasta onde o comando roda (padrão: /data/home)
--env stringArray: variável NOME=valor (repetível)
-i, --stdin: envia a entrada padrão local para o comando
--timeout int: prazo em segundos (1 a 600) (default 600)

puxadinho run [flags de create] [--push PASTA] [--pull CAMINHO]... [--timeout 600] -- COMANDO...

Cria uma box, roda um comando e apaga a box no fim

Cria uma box descartável, envia --push (a pasta vira o diretório de trabalho), roda o comando (até 600 s por exec; acima disso, como job), baixa cada --pull e apaga a box, mesmo com falha ou Ctrl-C. O servidor também recebe delete-after = timeout + 15 min, caso a CLI morra no meio. Sai com o código do comando; falha da infraestrutura (criar, enviar, baixar) sai com 125.

--all: no --push de pasta git, inclui os não rastreados (que o git não ignora)
--auto-suspend string: pausa por ociosidade: off ou de 5m a 30m
--cwd string: diretório de trabalho na box (padrão: a pasta do --push, ou /data/home)
--data-gib int: tamanho do /data em GiB (20 a 500)
--env stringArray: variável NOME=valor (repetível)
--max-run string: limite de tempo rodando: minutos, 0 (pausa já) ou unlimited (sem limite)
--mem-mib int: memória em MiB (2048 × vCPUs)
--metadata stringArray: metadado chave=valor (repetível)
--name string: nome da box (único no workspace; sem isso o servidor gera um)
--pull stringArray: caminho na box baixado depois do comando, relativo ao diretório de trabalho (repetível)
--push string: pasta (ou arquivo) local enviada antes do comando
--secret stringArray: nome de um Secret do workspace (repetível)
--setup-file string: script que roda depois do boot
--snapshot string: cria a partir de um snapshot (snp_…)
--template string: template: padrao ou midia
--timeout int: prazo do comando em segundos (default 600)
--vcpus int: vCPUs: 2, 4, 8, 16 ou 32

puxadinho jobs

Comandos longos em segundo plano (sem limite de tempo)

puxadinho jobs kill BOX JOB [--signal TERM]

Encerra um job

--signal string: sinal: TERM, KILL, INT ou HUP (default "TERM")

puxadinho jobs logs BOX JOB [-f]

Mostra a saída do job (-f acompanha até o fim)

-f, --follow: acompanha a saída até o job terminar
--offset int: começa neste byte da saída
--tail int: só as últimas N linhas

puxadinho jobs ls BOX

Lista os jobs da box

--status string: filtra: running, succeeded, failed ou killed

puxadinho jobs start BOX [--name N] [--cwd DIR] [--env K=V]... -- COMANDO...

Inicia um job; enquanto ele roda, a box não dorme por ociosidade

--cwd string: pasta onde o comando roda (padrão: /data/home)
--env stringArray: variável NOME=valor (repetível)
--name string: nome do job

puxadinho jobs wait BOX JOB

Espera o job terminar e sai com o código dele

--timeout duration: prazo máximo de espera (0 = sem prazo)

puxadinho ps BOX

Mostra os processos rodando na box

puxadinho history BOX

Histórico de comandos da box (o mais recente primeiro)

--limit int: quantos comandos mostrar (default 20)

puxadinho output BOX EXEC_ID

Mostra a saída guardada de um comando (últimos 64 KB por stream)

Mostra stdout e stderr guardados de um comando do histórico (exe_…, veja "puxadinho history BOX").

Arquivos

puxadinho files

Lista, lê e inspeciona arquivos da box

puxadinho files cat BOX CAMINHO

Mostra um arquivo da box (até 64 MB; maiores com pull)

puxadinho files ls BOX [CAMINHO]

Lista uma pasta (padrão: /data/home)

--limit int: máximo de entradas (default 1000)
-r, --recursive: inclui subpastas
--sort string: ordem: name, modified (mais recentes primeiro) ou size (default "name")

puxadinho files stat BOX CAMINHO

Mostra tipo, tamanho, permissões e data de um caminho

puxadinho push BOX LOCAL [REMOTO]

Envia um arquivo ou uma pasta para a box

Envia um arquivo ou uma pasta. REMOTO relativo parte de /data/home; sem REMOTO, vai para /data/home/<nome>. Pasta num repositório git: só os arquivos rastreados (--all inclui os não rastreados que o git não ignora). Sempre sem node_modules, .git, dist, build, .next, target, __pycache__ e o que estiver no .puxadinhoignore. Arquivos grandes vão em partes; se cair, rode de novo e só o que falta é enviado.

--all: inclui arquivos não rastreados pelo git (que o git não ignora)
--mode string: permissões do arquivo na box, em octal (ex.: 0755)

puxadinho pull BOX REMOTO [LOCAL]

Baixa um arquivo ou uma pasta da box

Baixa um arquivo ou uma pasta (pasta vem compactada, até 2 GB, e é extraída em LOCAL). REMOTO relativo parte de /data/home; sem LOCAL, grava ./<nome>. Arquivos vêm em partes em paralelo; se cair, rode de novo e o download continua do arquivo .part.

puxadinho cp ORIGEM DESTINO

Copia entre a máquina e a box (box:caminho indica o lado da box)

Copia arquivos ou pastas. O lado da box é escrito como box:caminho, por exemplo: puxadinho cp ./brutos render-ep12:brutos puxadinho cp render-ep12:out/episodio-12.mp4 .

--all: ao enviar pasta git, inclui os não rastreados (que o git não ignora)
--mode string: permissões do arquivo enviado, em octal

Portas e SSH

puxadinho port

Publica portas da box (HTTPS, ou TCP com TLS na 443)

puxadinho port ls BOX

Lista as portas publicadas

puxadinho port publish BOX PORTA [--tcp] [--public]

Publica uma porta (privada por padrão: exige o token)

--public: aberta para qualquer um (sem token)
--tcp: TCP com TLS/SNI na 443 em vez de HTTPS

puxadinho port rm BOX PORTA

Despublica uma porta

puxadinho port-forward BOX LOCAL:REMOTA

Encaminha uma porta local para a box por SSH (ssh -N -L)

Encaminha localhost:LOCAL para a porta REMOTA da box. Uma porta só (ex.: 3000) usa o mesmo número dos dois lados.

--print: só mostra o comando ssh, sem rodar

puxadinho ssh BOX [-- COMANDO...]

Entra na box por SSH (certificado de vida curta)

Entra na box com o ssh do sistema. A CLI gera (uma vez) a chave ~/.config/puxadinho/id_ed25519, pede um certificado de vida curta e confia no host pela linha @cert-authority do servidor. Com --print, só mostra o comando ssh.

--print: só mostra o comando ssh, sem rodar
--ttl int: validade do certificado em segundos (60 a 86400) (default 3600)

Snapshots

puxadinho snapshot

Salva e restaura o estado de uma box

puxadinho snapshot files SNAPSHOT

Lista os arquivos de um snapshot

--path string: diretório a listar (default "/data/home")

puxadinho snapshot get SNAPSHOT

Mostra um snapshot

puxadinho snapshot ls

Lista os snapshots · também: list

--box string: só os snapshots desta box (id bx_…)

puxadinho snapshot restore BOX SNAPSHOT

Restaura um snapshot na box (substitui root e /data; a box reinicia)

puxadinho snapshot rm SNAPSHOT

Apaga um snapshot · também: delete

puxadinho snapshot save BOX

Salva um snapshot da box

--metadata stringArray: metadado chave=valor (repetível)
--name string: nome do snapshot

Secrets

puxadinho secrets

Secrets do workspace (o valor nunca entra na box nem volta)

Secrets ficam cifrados no servidor. A box vê só um placeholder (pxd_secret_NOME), trocado pelo valor apenas nas requisições para os hosts liberados.

puxadinho secrets ls

Lista os Secrets (só nomes, hosts e placeholders)

puxadinho secrets rm NOME

Apaga um Secret

puxadinho secrets select BOX [NOME...]

Escolhe quais Secrets a box pode usar (substitui a seleção; sem nomes, limpa)

puxadinho secrets set NOME --host HOST... [--label R]

Cria ou troca um Secret (valor pelo stdin ou digitado, nunca como argumento)

Cria ou troca um Secret. O valor vem do stdin ou de um prompt sem eco, por exemplo: puxadinho secrets set ELEVENLABS_API_KEY --host api.elevenlabs.io <<< "$ELEVENLABS_API_KEY" --host é obrigatório (hostnames exatos, sem curinga; repetível).

--host stringArray: hostname exato que pode receber o valor (repetível)
--label string: rótulo para o painel (ex.: ElevenLabs)

Os comandos do MCP local e do setup estão explicados em Conectar o MCP.