Linha de comandos

ploy é o cliente de linha de comandos do núcleo do Ploy. Corre o mesmo orquestrador que a app, com os mesmos modelos e as mesmas ferramentas, para automatizar, testar e medir. Não vem dentro da app nem tem descarga própria: compila-se a partir do código-fonte do Ploy.

Compilar#

Precisas de macOS 26 e das ferramentas de Swift (o pacote pede a versão 6.2 ou posterior). Na raiz do código:

swift build
.build/debug/ploy version

O ploy procura o motor dos modelos em vendor/llama/llama-server, a partir da pasta do executável e subindo até seis níveis, ou usa o caminho que puseres em PLOY_LLAMA_SERVER. Se vendor/llama/ estiver vazio, scripts/fetch-runtime.sh descarrega o llama.cpp b11879 e verifica o SHA-256.

Os modelos são os mesmos da app, em ~/Library/Application Support/Ploy/Models/. Se não houver nenhum modelo do Ploy instalado, ploy run usa o ficheiro GGUF que passares com --model ou o caminho em PLOY_MODEL.

Subcomandos#

Só no macOS:

Há ainda selftest-orphan, que só os testes do Ploy usam. A ajuda curta mostra apenas run, models, platform, notices, serve e version.

ploy run#

A linha de comandos não tem a quem perguntar. O que passa do nível de --allow é recusado, e a linha dessa ação diz «Não autorizado». Depois de a tarefa ler conteúdo de terceiros, os comandos e a leitura fora da pasta são recusados, a não ser com --allow sensitive, que deixa correr tudo, incluindo o que é sensível e incluindo depois de conteúdo de terceiros. Não uses sensitive com pedidos que leiam a web. Os níveis estão em Segurança.

Sem --json, cada linha diz um passo: o modo e o modelo escolhidos, as ações (- A ler …), o resultado de cada uma ([ok], [falhou]), os ficheiros escritos ([ficheiro]), as verificações ([a verificar], [verificado], [problema]), as correções ([a corrigir]) e as notas ([nota]), e no fim «Verificado» ou «Não verificado» com o que ficou por confirmar e a pasta usada. Com --json, cada linha é um evento da tarefa, com a hora (time) e o tipo de passo (kind), como routed, toolStarted, fileWritten ou finished.

Os pedidos da linha de comandos não usam nem guardam memórias e não aparecem no histórico da app.

O código de saída de ploy run é 0 quando a tarefa ficou verificada, 1 quando não ficou ou falhou, e 2 quando falta o pedido ou não há modelo.

Exemplos:

# Corrigir um projeto com o Saturn
.build/debug/ploy run "Os testes deste projeto falham. Corrige o código, não os testes." --dir ~/projetos/loja --model saturn

# Uma pergunta de raciocínio para o Kant, sem pasta
.build/debug/ploy run "Um empréstimo de 200 000 euros a 30 anos com taxa fixa de 3% ao ano: quanto é a prestação mensal?" --model kant

# Uma imagem anexada, com os eventos em JSON
.build/debug/ploy run "Que número de encomenda está nesta imagem?" --attach ~/Desktop/encomenda.png --json

# Modelos
.build/debug/ploy models
.build/debug/ploy models pull qwen3.5-4b

# Ver o que o Ploy faria com uma aplicação, e verificar uma página
.build/debug/ploy apps "Bloco de Notas"
.build/debug/ploy inspect ~/projetos/calculadora/index.html

ploy serve#

ploy serve põe o núcleo à disposição de outra interface ou de um script, um objeto JSON por linha em cada sentido. É o protocolo pensado para uma interface de Windows, que ainda não existe.

• Pedido: {"id": 1, "method": "...", "params": {...}}.
• Resposta: {"id": 1, "result": ...} ou {"id": 1, "error": "..."}.
• Enquanto uma tarefa corre: {"id": 1, "event": ...}, um evento por linha, até à resposta final.

Um evento de autorização diz se «Nesta tarefa» e «Sempre» fariam alguma diferença (offersForRun, offersAlways), para que a interface esconda o que não teria efeito. Um método desconhecido recebe "Unknown method …", e uma linha que não é um objeto JSON com id e method recebe um erro sem id. Quando a entrada padrão fecha, as tarefas em curso param e o motor liberta o modelo. As tarefas do serve também não usam memórias.

Um exemplo, com a resposta real do hello neste Mac:

printf '%s\n' '{"id":1,"method":"hello"}' | .build/debug/ploy serve

{"id":1,"result":{"name":"Ploy","platform":"macOS","services":[{"available":true,"name":"Abrir aplicações"},{"available":true,"name":"Ler e controlar janelas"},{"available":true,"name":"Rato e teclado"},{"available":true,"name":"Capturas de ecrã"},{"available":true,"name":"Imagens"},{"available":true,"name":"Transcrição de voz"},{"available":true,"name":"Vídeo"},{"available":true,"name":"Navegador do agente"},{"available":true,"name":"Verificação de páginas"},{"available":true,"name":"Lixo recuperável"},{"available":true,"name":"Notificações"}],"version":"2.0"}}

E uma tarefa com uma autorização e uma paragem:

{"id": 3, "method": "run", "params": {"text": "Cria uma página com um relógio", "folder": "~/projetos/relogio", "model": "saturn", "mode": "confirm"}}
{"id": 4, "method": "approve", "params": {"approval": "<id do pedido de autorização>", "approved": true, "forRun": true}}
{"id": 5, "method": "stop", "params": {"run": 3}}

Os testes do Ploy exercitam este protocolo com o executável real.