celo — a Celoia no seu terminal

CLI da Celoia: conversa, lê e escreve os arquivos do projeto, roda comandos e olha imagens — com os modelos e os tokens do seu plano, sem sair do shell.

npm i -g @celoiaio/cli
celo login
celo

Precisa de Node 18.17 ou mais novo, uma conta na Celoia com plano ativo e o acesso por API liberado (hoje, beta fechado — o time libera a conta).

Comandos

| Comando | O que faz | |---|---| | celo | Abre a conversa | | celo -c | Continua a última conversa desta pasta | | celo -r / celo --resume | Escolhe uma conversa anterior desta pasta | | celo "pergunta" | Responde e sai | | cat erro.log \| celo "o que é isso?" | Usa o stdin como contexto | | celo login | Conecta este terminal à sua conta | | celo logout | Desconecta (a chave continua na conta, revogável no painel) | | celo whoami | Conta, plano, saldo e modelos | | celo atualizar | Instala a versão mais nova (dentro da conversa: /atualizar) | | -m, --model <id> | Escolhe o modelo desta execução | | -y, --yes | Deixa sobrescrever arquivos e rodar comandos sem perguntar | | -a, --auto | Não pergunta nada e vai até o fim da tarefa |

Dentro da conversa: /model, /limpar, /sessoes, /salvar, /auto, /historico, /notificar, /atualizar, /saldo, /ajuda, /sair. Shift+Tab gira o modo de autorização sem sair do que você está digitando:

❯ refaça o layout da home
  ⇧⇥ auto · grava, roda comando e segue até o fim

Três degraus: pergunta antes (padrão) → grava sem perguntar, mas ainda confirma comando → auto, que grava, roda comando e segue até o fim. A linha fica sempre à vista, inclusive no modo padrão — indicador que some não responde "em que modo eu estou?". Ela lê o estado real: responder sempre no meio de uma resposta acende o indicador do mesmo jeito.

Digitando / a lista aparece filtrada; Tab completa o primeiro. /model e /sessoes abrem um menu navegável (↑↓, Enter, Esc).

Ele mexe nos arquivos

Peça e ele faz — não devolve o conteúdo para você copiar:

❯ crie docs/index.html com uma página de documentação
  ⏺ criar docs/index.html · 105 linhas
  ✓ criou docs/index.html · 105 linhas

Alterando um arquivo que já existe, ele mostra o que mudou:

  ✓ atualizou src/index.css  · +8 −2
     4 - min-width: 7ch;
     5 - max-width: 40ch;
     4 + /* Largura mínima de verdade: força a tabela a ROLAR */
     5 + min-width: 16ch;

Sete ferramentas: ler, listar, buscar, escrever, editar, executar comando (git, npm, testes, build) e ver imagem.

Para mudar algo num arquivo que já existe ele edita o trecho, em vez de reescrever tudo — num arquivo de 300 linhas, trocar duas custa duas, não trezentas. Ele investiga antes de perguntar — "onde fica o frontend?" se responde procurando, não devolvendo a pergunta. Duas regras:

• Nada sai da pasta atual. Todo caminho é resolvido contra o diretório onde você abriu o celo; o que escapar dele é recusado.
• Escrita pede licença. Ler é livre. Gravar mostra o arquivo e pergunta (s / N / sempre). No modo celo "pergunta", criar arquivo novo é liberado, mas sobrescrever exige --yes — o trabalho que já existe não se apaga sozinho.

Rodar comandos

❯ faça o commit disso
  ⏺ git add .  · preparar os arquivos alterados
    rodar? [s/N/sempre] s
  ✓ git add . → ok

Cada comando é mostrado com o motivo e pede confirmação (s / N / sempre). Comandos irreversíveis — rm -rf, git push --force, git reset --hard, formatar disco — são recusados antes mesmo de perguntar. No modo celo "pergunta" nada roda sem --yes.

Ele enxerga print

Cite o caminho de uma imagem na sua pergunta e ela vai junto — arrastar o arquivo para dentro do terminal também funciona, porque o caminho chega entre aspas:

❯ 'C:\Users\voce\Downloads\Screenshot_2.png' por que esse menu está torto?
  ⏺ olhando Screenshot_2.png  · 15 KB

Vale qualquer pasta do computador: quem cola o caminho está autorizando aquele arquivo. A trava de pasta continua valendo para o que o modelo escolhe sozinho — o ver_imagem, que ele usa para abrir um print de dentro do projeto, não sai do diretório atual.

Formatos: png, jpg, gif, webp e bmp, até 5 MB por imagem e 4 por mensagem. A conversa guarda o caminho, não os bytes, e a imagem acompanha as duas últimas trocas — depois disso o modelo vê só uma nota dizendo que ela existiu, porque cada reenvio é cobrado de novo. Modelo sem visão (DeepSeek, o3-mini) recusa com o nome dele na mensagem; /model troca.

Ele te chama de volta

Pedido grande leva minutos, e você vai fazer outra coisa. O celo avisa quando termina — e, principalmente, quando para esperando você: um [s/N] para gravar um arquivo deixa o terminal parado o tempo que for.

❯ /notificar
  avisa por "maestri notify" depois de 30s de trabalho
  mandei um aviso de teste agora

Dentro do Maestri já vem ligado — o celo acha o maestri notify sozinho. Fora dele, aponte para o que você usa:

/notificar ntfy publish meu-topico          # celular
/notificar off                              # cala

Também por env: CELO_NOTIFICAR="terminal-notifier -message {msg}". O comando recebe a mensagem como último argumento, ou no lugar de {msg} se você marcar onde. CELO_NOTIFICAR_APOS=60 muda o tempo mínimo (padrão 30s): pedido que responde rápido não avisa ninguém, porque você estava olhando.

Tarefa longa

Um pedido grande usa ferramenta muitas vezes: ler, procurar, editar, rodar o teste, corrigir. A cada 25 idas e voltas o celo para e pergunta:

    25 idas e voltas neste pedido · continuar? [S/n/sempre]

Enter continua (é o padrão), sempre libera o resto da conversa. O Shift+Tab até o modo auto — ou /auto, ou celo --auto "..." — liga isso de saída: ele grava, roda comando e vai até o fim sem interromper. É o modo de largar rodando e ir fazer outra coisa.

O único teto que resta é 200 idas e voltas por pedido: a rede contra o modelo que se perde e fica lendo arquivo até o saldo acabar.

Bloco de código longo na resposta aparece resumido (… +42 linhas) com a moldura e o rótulo da linguagem; /salvar arquivo.txt grava o último bloco inteiro.

Retomar

celo -c volta para a última conversa desta pasta. celo -r (ou --resume) e /sessoes mostram somente as conversas daqui, sem misturar outros projetos. Se não houver histórico nesta pasta, começa uma conversa nova. Abra o terminal na pasta do projeto antes de retomar; a pasta de origem da conversa não muda ao salvar.

O histórico fica completo no disco: só o contexto enviado ao modelo é reduzido. A pergunta é salva ao entrar e o progresso após cada rodada de ferramentas, para não perder o trabalho já registrado se o saldo acabar na chamada seguinte.

Ao retomar, a conversa volta inteira na tela, quebrada na largura do terminal — você pediu -r para ver de onde parou, e o terminal tem rolagem. Só uma conversa muito longa é cortada, pelo fim, dizendo quantas mensagens ficaram para trás; /historico traz todas, e /historico 80 limita às últimas 80 linhas.

Quanto custa

O CLI gasta os tokens do seu plano da Celoia — os mesmos do chat, no mesmo peso (o ×N que aparece no seletor de modelos). Cada resposta mostra quanto consumiu e quanto sobrou; /saldo consulta a qualquer momento, e o número fica âmbar abaixo de 200 mil tokens e vermelho abaixo de 50 mil.

Modelo caro em conversa longa consome rápido: /model claude-haiku-4-5 resolve a maior parte das perguntas por uma fração do custo.

Como o login funciona

Nenhuma senha passa pelo terminal. O celo login pede um par de códigos ao backend, mostra o curto (QK7T-2M9P), abre o navegador em /device e fica perguntando se já foi aprovado. A pessoa confere de qual máquina veio o pedido e autoriza; só então o backend cria a API key e a entrega ao terminal, uma única vez.

A chave criada é uma API key normal da Celoia: aparece em Configurações › OpenCode / API, com nome Celo CLI · usuário@máquina, e pode ser revogada de lá.

Onde ficam as coisas

| Caminho | Conteúdo | |---|---| | ~/.celo/config.json | API key, base da API, último modelo (permissão 0600) | | ~/.celo/sessions/*.json | Histórico das conversas, só nesta máquina |

Variáveis de ambiente

| Variável | Para que serve | |---|---| | CELO_API_BASE | Aponta o CLI para outro backend (ex.: http://127.0.0.1:8001/v1). Vence o config | | CELO_NOTIFICAR | Comando que avisa quando o trabalho termina (off cala). Dentro do Maestri, automático | | CELO_NOTIFICAR_APOS | Segundos de trabalho antes de valer um aviso (padrão 30) | | CELO_NO_BROWSER | Não tenta abrir o navegador no login — para servidor via SSH | | NO_COLOR | Saída sem cor (também detectado automaticamente fora de TTY) |

Desenvolvimento

Sem dependências: só a biblioteca padrão do Node 18+. Para rodar contra o backend local:

export CELO_API_BASE=http://127.0.0.1:8001/v1
node bin/celo.js login

| Arquivo | Responsabilidade | |---|---| | bin/celo.js | Argumentos, stdin canalizado, despacho | | src/login.js | Device code flow | | src/chat.js | REPL e pergunta única | | src/api.js | HTTP: /v1/me, /v1/chat/completions (SSE), device flow | | src/tools.js | As ferramentas e a instrução de sistema | | src/imagem.js | Anexo de imagem: acha o caminho, lê do disco, monta a parte | | src/notificar.js | O aviso de fim e de espera — roda o comando que você escolher | | src/session.js | Histórico local | | src/config.js | ~/.celo/config.json | | src/ui.js | Cor, spinner, markdown de terminal |

O que vem depois

Leitura, busca, escrita, edição por trecho, comandos e imagem já estão de pé. Na fila:

• Allowlist de comandos por projeto, para o --auto não depender de confiar em tudo.
• celo push / celo pull ligando o terminal ao Criador de Apps.