docs · beta

Documentação do Aluy CLI

Tudo para instalar, configurar e colocar o agente para trabalhar — do primeiro comando ao ciclo autônomo, a referência completa do CLI e dos comandos slash, o layout .aluy/ e a compatibilidade. Código aberto sob MIT.

01 · início

Visão geral

O Aluy CLI é seu agente local que trabalha em escala. Em vez de sugerir código para você copiar e colar, ele age no seu projeto: lê e edita arquivos, roda comandos e fala com ferramentas — de ponta a ponta, na sua shell.

O que roda na sua máquina fica na sua máquina: a sessão, o histórico, os arquivos, a memória e a chave de provider (guardada no cofre do SO). A única coisa que cruza a borda é a chamada ao modelo — por padrão o Aluy cuida dessa conexão, ou você liga o seu próprio provider direto.

É código aberto, sob a licença MIT: o que age na sua máquina, você pode ler, auditar e mudar. A missão é simples — democratizar a automação de tarefas, processos, testes e desenvolvimento, sem depender de um time de plataforma.

O Aluy CLI é o agente de terminal — não é o orquestrador de histórias, ADRs e sprints na plataforma Aluy. Aqui o foco é agir no seu projeto.

02 · início

Instalação

Instale em um comando, como seu usuário, sem sudo. O instalador resolve as dependências e coloca o aluy no PATH; re-rodar atualiza. A instalação vive em ~/.aluy.

Linux · macOS

$ curl -fsSL https://aluy.dev/install.sh | bash

Windows (PowerShell)

PS> irm https://aluy.dev/install.ps1 | iex

Requisitos: Linux, macOS ou Windows · Node ≥ 20 (o instalador garante) · ~150 MB livres · conexão no primeiro run.

Guia completo de instalação →

03 · início

Primeiros passos

No seu primeiro aluy, um assistente abre e pede, nesta ordem, provider, chave e modelo.

Provider — por padrão, o Aluy cuida da conexão com o modelo e você não configura nada. Ou escolha um provider direto, com a sua credencial. Troque depois com /provider.
Chave — vai direto pro cofre do SO (Keychain no macOS, libsecret no Linux, Credential Manager no Windows). Nunca em texto, nunca no repo.
Modelo — escolha o tier com /model; ajuste o esforço de raciocínio com /effort quando precisar.

Então mande a primeira tarefa: abra a sessão, descreva o objetivo (ou use um /comando) e deixe o agente trabalhar. Cada ação que toca seus arquivos pede permissão.

Duas flags definem isso desde o início: aluy --plan roda somente-leitura (analisa e propõe, sem efeito); aluy --yolo deixa rodar sem supervisão, auto-aprovando todo efeito — exceto as categorias sempre-perguntar (exclusão, rede, escalada de privilégio, instalação de pacote), que seguem travadas, e recusa rodar como root. Detalhes na referência de CLI.

$ aluy            # abre a sessão neste projeto
› digite um objetivo, ou um /comando:
/doctor          # checa a saúde da instalação
/init            # cria o AGENT.md do projeto
/cycle "rode os testes e conserte o que quebrar"

Quer ligar memória de longo prazo, mais fôlego de contexto ou modelos locais? Rode aluy bootstrap — veja a seção Sidecars.

04 · referência

Referência de CLI

São os comandos que você roda na sua shell — aluy e seus subcomandos. Rode aluy --help para a lista embutida e aluy --version para imprimir a versão. O padrão (sem subcomando) abre a sessão interativa.

Sinopse

$ aluy [objetivo] [flags…]       # abre a sessão (opcionalmente com um objetivo)
$ aluy <subcomando> [flags…]      # login, doctor, mcp, cron, bootstrap…
$ aluy -p "<objetivo>" [flags…]   # headless one-shot (modo print)

O comando padrão

Rodar aluy sem subcomando abre a sessão TUI interativa no diretório atual. Uma string entre aspas isolada vira o objetivo inicial: aluy "refatore o módulo de auth". O primeiro token sem flag é o objetivo. No primeiríssimo run — quando ainda não há config — o assistente interativo de primeira execução abre automaticamente antes da sessão, passando por idioma, backend, provider e modelo.

Flags de topo

-v, --version info

Imprime a versão e sai imediatamente, antes de montar a TUI. Formato: aluy <cli> (@hiperplano/aluy-cli-core <core>).

-h, --help info

Imprime o texto de ajuda embutido completo (todos os comandos e flags) e sai.

--yolo sessão · segurança

Permissão total na máquina: auto-aprova todo efeito, exceto as categorias sempre-perguntar, que seguem inflexíveis. Recusa rodar como root (uid 0). Em TTY pede confirmação uma vez; em headless (-p) entra direto. O alias depreciado --unsafe ainda funciona, mas emite um aviso.

--plan sessão · segurança

Modo de planejamento somente-leitura: o agente analisa e propõe, mas não produz efeito. Se --plan e --yolo forem passados juntos, --plan vence.

Modo headless / print

-p, --print, --exec scripting

Run headless one-shot: executa um único objetivo, imprime o resultado, sai. O prompt pode ser inline (-p "objetivo") ou vir por stdin (echo "objetivo" | aluy -p). --print e --exec são aliases.

--output-format text|json|stream-json scripting

Só válido com -p. text (padrão) imprime só o resultado; json imprime um objeto numa linha; stream-json emite um fluxo NDJSON de eventos ao vivo.

--quiet scripting

Só com -p: cala os ticks de progresso e o ruído do stderr, deixando só o resultado. Ideal para pipes e CI.

--cycle, --cycles <N>, --cycle-for <dur> scripting

Só com -p: roda o objetivo autonomamente em ciclos (a forma headless do /cycle). Exige um teto — --cycles <N> (máximo de iterações) ou --cycle-for <dur> (relógio de parede, ex.: 30m, 2h). Anti-runaway: ambos são clampados em limites duros.

Modelo e backend

--tier <tier> modelo

Escolhe o tier de modelo da sessão (alterável em runtime com /model). Passar o literal custom sem --model é erro de uso.

--model <slug> · --provider <name> modelo

--model seleciona um slug curado de modelo do catálogo e força tier: custom. --provider precisa vir pareado com --model. Ambos são dado, nunca credencial — o broker resolve slug/provider para uma credencial server-side.

--effort <value> modelo

Passthrough de esforço de raciocínio (qualquer valor não-vazio ≤ 32 chars, ex.: low/medium/high). Sem tier-gate; o broker/provider valida o valor.

--backend broker|local backend

Escolhe como o modelo é alcançado. broker (padrão) roteia a chamada pelo broker do Aluy. local fala com o seu provider direto, com a sua credencial (BYO) do cofre do SO.

--local-provider · --local-model · --local-auth · --local-base-url backend · local

Só sob --backend local. --local-provider é anthropic|openrouter|openai; --local-model é o slug nativo do provider; --local-auth é apikey|oauth; --local-base-url é o endpoint (protegido por anti-SSRF). Cada um cai no env (ALUY_LOCAL_*) ou na config quando omitido.

Limites e segurança

--max-tokens <N> · --max-iterations <N> · --max-output-tokens <N> budget

--max-tokens é o budget de tokens da sessão (padrão 1000000); --max-iterations limita o loop modelo→tool→observação (padrão 300); --max-output-tokens limita o output por chamada. Ao bater um teto o run pausa e pergunta se continua ou para. Cada um é clampado.

--budget / --no-budget budget

Liga/desliga o circuit-breaker de budget da sessão. Padrão off em --backend local (BYO, ilimitado por design), sempre on com o broker.

--self-check / --no-self-check qualidade

Força o loop de self-check on ou off (re-âncora o objetivo e verifica antes de declarar "pronto"). Sem a flag é automático: tiers mais fracos ligam.

--autocompact-at <razão|%|off> contexto

Limiar de ocupação da janela que dispara a auto-compactação (padrão 0.85). Aceita 0..1, uma porcentagem (85%), ou off. O atalho --no-autocompact equivale a --autocompact-at off.

--no-subagents agentes

Desliga os sub-agentes locais paralelos (a tool spawn_agent). Por padrão os sub-agentes rodam em paralelo com profundidade ≤ 1, herdando permissões e um teto compartilhado.

Sessão, retomada e exibição

--continue · --resume [<id>] · --new sessão

--continue retoma a última sessão deste diretório. --resume sem id lista as sessões salvas; com um id retoma aquela. --new começa do zero.

--lang pt-BR|en ui

Idioma da TUI. Precedência: flag > config > auto-detect do locale > padrão pt-BR. Não traduz o output do agente. Troque em runtime com /lang.

--split · --fullscreen ui

--split começa em View Avançado (CHAT | LOG lado a lado; Ctrl+L alterna). --fullscreen começa em modo Cockpit (alt-screen). Ambos persistem na config.

--dense · --ascii ui

--dense compacta a TUI. --ascii usa um perfil seguro de glifos para evitar "tofu" Unicode (igual a ALUY_SAFE_GLYPHS=1).

Subcomandos

aluy bootstrap [--agent] setup · sidecars

Provisiona os sidecars locais (mem0, headroom, ollama) em user space — oferece cada um e você escolhe. --agent deixa o Aluy instalá-los pelo próprio agente em sistemas sem artefato pinado. Não existe subcomando aluy onboard: o assistente interativo de primeira execução (idioma, backend, provider, modelo) abre automaticamente na primeira vez que você roda aluy.

aluy login [--token <PAT>] [--org <id>] [--device] [--provider <p>] [--oauth] conta

Autentica. Por padrão roda o device-flow do broker. --token passa um Personal Access Token direto (CI); --org escolhe uma organização; --provider faz login num backend local (BYO), e com --oauth faz um login OAuth-PKCE.

aluy logout · aluy whoami conta

logout revoga a sessão e apaga a credencial do keychain. whoami mostra o usuário, org e escopos atuais — nunca o segredo.

aluy doctor [--deep|--test] [--json] saúde

Valida a instalação: credencial, broker, servers MCP, perfis de agente, config, versão e memória. --deep adiciona um teste do tier ao vivo (gasta uma chamada ao modelo). --json imprime um array legível por máquina; o exit code é diferente de zero se algum check falhar.

aluy agents · skills · workflows · models · providers descoberta

Listagens somente-leitura, exit 0, sem chamada ao modelo. Mostram os perfis de agente .md mapeados, as skills SKILL.md, as definições de workflow e os providers/modelos disponíveis (catálogo do broker + local BYO).

aluy mcp <search|add|list|remove> ferramentas

Gerencia conectores MCP pela shell (o mesmo motor do /mcp na sessão). add <nome> -- <cmd> adiciona um server stdio local; --project escreve no .mcp.json do projeto.

Agenda tarefas headless persistentes pelo agendador do SO (sem daemon). Disponível no Linux (crontab); Windows/macOS a caminho. Cada run executa como aluy -p "<tarefa>" pela trava de permissão. add <quando> "tarefa" recebe um cron de 5 campos (ex.: "0 9 * * 1-5"); list mostra id, on/off, agenda, tarefa e yolo; edit / rm / run <id> reconfiguram, removem ou rodam agora; enable / disable <id> alternam sem apagar.

Variáveis de ambiente

Várias flags leem uma env var correspondente como fallback: ALUY_TOKEN, ALUY_ORG, ALUY_BACKEND, ALUY_LOCAL_*, ALUY_MAX_TOKENS, ALUY_BUDGET, ALUY_AUTOCOMPACT_AT, ALUY_SAFE_GLYPHS. NO_COLOR desliga a saída colorida.

Exit codes: 0 sucesso · 1 erro · 2 erro de uso — sai sem montar uma sessão.

05 · referência

Comandos slash

Dentro de uma sessão em execução, digite / no início da linha para abrir o menu — filtre enquanto digita, e Tab/Enter completa. São comandos que você dá, não tools que o agente invoca. Uma visão compacta e agrupada está na página Comandos.

Conta e sessão

/login · /logout · /whoami · /doctor conta · somente-leitura

Entra/sai e inspeciona a sessão. /whoami mostra usuário, org, escopos e uma dica de token redigida — nunca o segredo. /doctor é o health check somente-leitura (credencial, broker, catálogo, MCP, perfis, config, versão, memória) — cada ✓/⚠/✗ com uma dica de conserto. Ambos rodam em paralelo no meio do turno.

/help · /usage · /rename · /history sessão

/help lista todo comando nativo; /usage mostra tokens, ocupação da janela e tier. /rename dá um rótulo + cor à sessão (também define o título da janela do terminal). /history navega e retoma uma sessão anterior sem sair do Aluy.

/compact · /clear [full|memory] · /ask · /notify sessão · contexto

/compact resume a conversa para encolher a janela. /clear limpa o contexto; memory/full também apagam a memória (confirma). /ask é uma pergunta paralela somente-leitura. /notify alterna a campainha de atenção.

Workspace, projeto e config

/undo · /redo · /rewind workspace

Avança/volta a última edição de arquivo do agente pelo journal da sessão. /rewind (Esc Esc) volta a um checkpoint anterior — código e/ou conversa.

/permissions · /tools · /add-dir workspace

/permissions mostra as regras (read=allow, write/bash=ask, sempre-perguntar=travado). /tools é o inventário unificado somente-leitura (nativas, MCP por server, tools de delegação, estado de permissão). /add-dir autoriza um diretório extra para a sessão.

/init · /memory · /todo projeto

/init analisa o repo e escreve o AGENT.md (você confirma o diff). /memory <list|forget|edit|pin|unpin> cura a memória do agente (global + projeto; um fato fixado segue dado, nunca instrução). /todo gerencia o backlog persistente.

/model · /provider · /effort · /theme · /lang · /split · /fullscreen config · ui

/model troca o tier (mostra só o tier, nunca a credencial); /provider define o nome do provider para o modo Custom; /effort define o esforço de raciocínio. /theme aluy-dark|aluy-light|aluy-slate e /lang (pt-BR/en) persistem a escolha. /split e /fullscreen alternam o painel LOG e o modo Cockpit.

Autonomia e multi-agente

/cycle <intervalo|--por dur|--auto> "tarefa" autonomia

Roda uma tarefa em ciclos até terminar, com tetos duros e parada automática (anti-runaway), pela mesma catraca de permissão. Dois ritmos: fixo (5m ou --por <dur>) ou --auto. Em voo: pause, resume, edit, status, stop.

/cron · /subagent · /back · /rooms agendamento · multi-agente

/cron é a forma em-sessão do aluy cron. /subagent <nome> abre um foco 1:1 com um perfil; /back volta. /rooms <list|new|read|watch> cria e acompanha salas agente-a-agente ao vivo.

/agents · /skills · /workflows · /mcp descoberta · ferramentas

Dentro da sessão, digite /help para a lista ao vivo, ou Ctrl+P para a paleta de comandos. Os aliases /view → /split e /cockpit → /fullscreen resolvem automaticamente.

06 · referência

Estrutura .aluy/

O Aluy mantém duas casas: uma global em ~/.aluy/ (instalação, config, sidecars, memória entre projetos) e uma de projeto — o arquivo de instrução na raiz do repo mais uma pasta .aluy/ opcional. Tudo sob ~/.aluy/ é o kernel-cliente confinado: as próprias regras de path-deny do agente o proíbem de ler, editar ou rodar qualquer coisa ali.

Projeto: o arquivo de instrução

O arquivo de instrução nativo do projeto é o AGENT.md na raiz do repo — o que o /init cria. O Aluy lê três nomes de arquivo como instruções de projeto, nesta precedência, compondo todos os presentes:

<seu-projeto>/ ├── AGENT.md # nativo do Aluy (primário — o que o /init escreve) ├── AGENTS.md # Codex / OpenAI └── CLAUDE.md # Claude Code / Anthropic

A precedência é AGENT.md › AGENTS.md › CLAUDE.md. São lidos uma vez na largada e injetados no system prompt, cada um sob um cabeçalho marcando a origem. Symlinks que escapam da raiz do projeto são rejeitados e nada é lido.

Projeto: a pasta .aluy/

<seu-projeto>/.aluy/ ├── agents/*.md # perfis de sub-agente do projeto ├── commands/*.md # comandos slash custom do projeto ├── skills/<nome>/SKILL.md # skills do projeto ├── workflows/*.md # definições de workflow do projeto └── memory/project.md # memória do agente com escopo de projeto # também lido (compat Claude Code): .claude/agents · commands · skills · workflows

Global: ~/.aluy/

~/.aluy/ ├── config.json # tema, tier, lang, split/fullscreen, backend… ├── providers.json # overrides de provider custom compatível com OpenAI ├── mcp.json # configuração global de servers MCP ├── audit.jsonl # log de auditoria de entrada em yolo ├── sessions/<id>.json # transcrições + metadados das sessões salvas ├── todos/<sessionId>.json # backlog de tarefas por sessão ├── undo/<sessionId>/ # journal de edições + blobs de conteúdo ├── memory/ │ ├── global.md # memória do agente entre projetos │ └── project.md # espelho da memória do projeto ativo ├── agents/ commands/ skills/ workflows/ # assets .md globais ├── cron/jobs.json # jobs cron agendados ├── rooms/<code>.jsonl # conversas das salas inter-agente ├── ollama/ # sidecar ollama: bin + modelos ├── mem-venv/ # venv do sidecar mem0 └── hr-venv/ # venv do sidecar headroom

Os três diretórios de sidecar só aparecem depois que você roda aluy bootstrap e escolhe provisioná-los. Sem os sidecars o Aluy ainda funciona — só perde memória de longo prazo, fôlego extra de contexto e modelos locais.

07 · em foco

/cycle — roda até terminar

Com o /cycle, você descreve a tarefa e o agente trabalha em ciclos por conta própria até terminar — sem babá. É o "dispare e vá fazer outra coisa".

Vem com um freio de mão: tetos duros de tempo e de passos, e parada automática se algo sair do trilho. O anti-runaway — nada de robô fugindo do controle.

/cycle "rode a suíte de testes e conserte o que quebrar"

Bom para: consertar testes, varreduras em massa, migrações repetitivas, tarefas longas com um critério claro de "pronto".
Todo efeito que toca seus arquivos ainda passa pela trava de permissão.

08 · em foco

Subagentes

Cada subagente é um perfil (arquivo .md) com o seu próprio foco. Você pede o especialista e o próprio agente cria o subagente para você — descreva o que precisa ("um revisor de segurança", "um QA de E2E") e ele gera o perfil com o papel, o tom e os limites. Você não escreve o .md na mão (mas pode editar ou criar um se quiser).

Eles trabalham em paralelo, sem misturar contextos: cada subagente tem sua própria sub-sessão dedicada. Uma frota, não um agente sozinho.

/subagent reviewer # abre um foco 1:1 com o perfil "reviewer"

09 · em foco

Salas

As salas (/rooms) colocam vários agentes conversando entre si sobre o mesmo problema — debatendo, dividindo e combinando o trabalho. Você acompanha a conversa em tempo real e entra quando fizer sentido.

$ /rooms new      # cria uma sala
$ /rooms list     # lista as salas ativas
$ /rooms watch    # observa a frota colaborar ao vivo

10 · em foco

MCP — conecte ferramentas

Pelo MCP (o padrão aberto de conectores), o agente fala com ferramentas e integrações externas — bancos, APIs, serviços. É o que dá ao agente acesso real ao que você já usa, não só conversa.

$ /mcp search      # busca conectores no registro
$ /mcp add         # adiciona um servidor local
$ /mcp list        # lista e liga/desliga conectores

11 · interoperável

Compatibilidade — Codex e Claude Code

Já usa Codex ou Claude Code? O Aluy entende a sua estrutura. Sem reconfig. Aponte o Aluy para o seu projeto e ele lê os mesmos arquivos de instrução e configuração que você já mantém.

Arquivos de instrução do projeto

AGENT.md — o arquivo nativo do Aluy (o que o /init escreve), também a convenção genérica de agente.
AGENTS.md — o mesmo arquivo que o Codex (OpenAI) usa.
CLAUDE.md — o mesmo arquivo que o Claude Code usa.

A precedência é AGENT.md › AGENTS.md › CLAUDE.md — todos os presentes compõem juntos.

Paridade de estrutura

Agentes .md aceitam os nomes de ferramentas do Claude Code — mapeados para os nativos.
Hooks no formato settings.json do Claude Code, e comandos de usuário em .md.
/rewind + checkpoints, com paridade ao Claude Code.

12 · avançado

Sidecars

Sidecars são reforços locais opcionais que rodam na sua máquina (escutando só em 127.0.0.1) para dar ao agente memória de longo prazo, mais fôlego de contexto e modelos locais. O Aluy funciona sem eles — só perde esses recursos. Nada quebra. Ligue com aluy bootstrap.

mem0 — memória entre sessões: guarda fatos e preferências e os traz de volta na próxima conversa.

headroom — mais fôlego de contexto: condensa o que já passou e mantém a janela do modelo sob controle.

ollama — modelos rodando na sua máquina para tarefas internas de apoio, sem mandar nada pra fora.

13 · avançado

Arquitetura

Por baixo dos panos, o Aluy CLI é um único processo no seu terminal — entrega monolítica, sem servidor escondido. A interface (a TUI) fala com o core, o motor que lê e edita arquivos, roda comandos e decide os próximos passos. Entre o agente e o seu projeto fica a trava de permissão: o único ponto por onde todo efeito passa antes de acontecer.

O estado vive na sua máquina: a memória da sessão (e a de longo prazo via mem0), sua chave no cofre do SO, seus arquivos e sua shell. Sidecars são reforços locais opcionais que escutam só em 127.0.0.1.

As únicas coisas que cruzam a borda são a chamada ao modelo e os conectores MCP que você liga.
Sessão, histórico, arquivos, memória e sua chave nunca saem do seu computador.

A trava de permissão é um ponto único: nenhum arquivo é alterado e nenhum comando roda sem passar por ela. É o que mantém você no controle.

14 · avançado

Memória

O agente lembra decisões e contexto do projeto de uma conversa para a outra — fatos globais e por projeto. Você controla tudo com /memory: veja o que ele guardou, fixe o que importa e esqueça o que não serve mais.

$ /memory list           # o que ele lembra aqui
$ /memory pin "..."       # fixa um fato importante
$ /memory forget "..."    # esquece um fato

A memória de longo prazo depende do sidecar mem0; sem ele, só vale a memória da sessão atual.
/clear memory apaga tudo o que o agente guardou (pede confirmação).

15 · avançado

Temas

A sessão vem em três temas — light, dark e slate — para você deixar do jeito que gosta de olhar o dia todo. Troque com /theme aluy-dark | aluy-light | aluy-slate; a sua escolha é salva.

Light · aluy-light — fundo pedra clara, acento âmbar.

Dark · aluy-dark — quase preto, alto contraste.

Slate · aluy-slate — pedra profunda com fios teal.

Os temas vêm dos tokens do Aluy Design System: cor, tipografia e densidade saem de variáveis, nunca de estilo cru.

16 · avançado

Doctor

/doctor é o diagnóstico somente-leitura da sua instalação: checa modelo, chave, conexão, MCP e config — e aponta uma dica de conserto quando algo está fora do lugar. Não muda nada, só lê.

$ /doctor
✓ modelo      ok
✓ chave       no cofre do SO
✓ conexão     ok
✓ MCP         2 conectores ativos

17 · perguntas

FAQ

Meus dados vão para a nuvem?

Não. A sessão, o histórico, os arquivos do projeto e a memória ficam na sua máquina. A única coisa que cruza a borda é a chamada ao modelo.

Onde mora a minha chave?

No cofre do SO (Keychain, libsecret, Credential Manager) — nunca em texto, nunca no repo. O Aluy mostra o tier do modelo, nunca a credencial.

Como o Aluy fala com o modelo?

Por padrão, o Aluy cuida da conexão com o modelo — você não configura nada. Se preferir, ligue o seu próprio provider direto, com a sua credencial (API key ou OAuth): é o seu uso, sob o seu controle.

Tem custo?

O Aluy CLI é código aberto, sob MIT. No modo direto, o uso do modelo corre pela sua própria conta no provider. Os sidecars rodam localmente, sem custo de API.

É seguro deixar o /cycle rodando sozinho?

O /cycle tem tetos duros de tempo e de passos, e parada automática. E toda ação que toca seus arquivos passa por uma trava de permissão.

Posso ler e modificar o código?

Sim — é código aberto sob MIT. Leia, audite, abra issues e faça fork. O que age na sua máquina, você merece poder inspecionar. O Aluy está em beta; espere arestas e iteração rápida.

Não achou a resposta? Comece pela página Instalar ou rode /doctor dentro da sessão.