CLI do Dukk — referência completa

Visão geral

O CLI é distribuído como um único binário chamado dukk. Sem nenhum subcomando, dukk abre a TUI interativa (REPL); com um subcomando ou com dukk prompt, ele executa uma ação e sai. O parsing de argumentos é hand-rolled (não usa clap): as flags globais (--model, --permission-mode, --output-format, --dangerously-skip-permissions, --no-tui, --swd, flags de budget, etc.) vêm antes do subcomando.

Instalação

# macOS / Linux
curl -fsSL https://get.nexcode.live | sh

# Windows (PowerShell)
irm https://get.nexcode.live/ps | iex

O instalador coloca o binário em /usr/local/bin/dukk (ou equivalente no PATH).

Invocação

# Abre a TUI interativa (sem subcomando)
$ dukk

# Ajuda geral e por subcomando
$ dukk --help
$ dukk prompt --help

# Versão
$ dukk --version

Modo inline (prompt)

dukk prompt "<texto>" roda um prompt único de forma não-interativa e sai — ideal para scripts, pipelines e automações. Combine com as flags globais para controlar modelo, permissões e formato de saída.

Exemplos básicos

# Prompt simples (texto na saída padrão)
$ dukk prompt "explique o que faz a função main do projeto"

# Várias palavras viram um único prompt (não precisa de aspas, mas recomenda-se)
$ dukk prompt resuma o README em 3 bullets

Escolhendo modelo e formato de saída

# Saída JSON estruturada (ótimo para parsear em scripts)
$ dukk --output-format json prompt "liste os endpoints da API"

# Saída em texto (default)
$ dukk --output-format text prompt "gere testes para o módulo de auth"

# Trocar o modelo só para esta execução (nome completo ou alias)
$ dukk --model claude-haiku-4-5-20251001 prompt "revise este diff em busca de bugs"

--output-format aceita apenas text ou json (não há ndjson). A opção -p/--print também força saída não-interativa.

Permissões em automações

# Modo somente-leitura: o agente não modifica arquivos
$ dukk --permission-mode read-only prompt "audite a segurança do crate server"

# Workspace-write: permite escrita dentro do workspace
$ dukk --permission-mode workspace-write prompt "aplique o lint fix sugerido"

# Pula TODAS as confirmações de permissão (acesso total — use com cuidado)
$ dukk --dangerously-skip-permissions prompt "renomeie a variável foo para bar em todo o projeto"

# Forma curta de prompt one-shot (compat Elai Code): -p
$ dukk -p "explique a arquitetura do crate server"

Flags globais

Aplicáveis a qualquer invocação do dukk, antes do subcomando. Extraídas do parser real (parse_args() em main.rs).

Subcomandos

Use dukk <subcomando> --help para o texto autoritativo de cada um.

$ dukk prompt "qual a arquitetura do crate server?"
$ dukk --output-format json prompt "liste as migrations pendentes"

$ dukk login --claudeai
$ dukk login --import-claude-code
$ echo "sk-ant-..." | dukk login --api-key --stdin

$ dukk logout

$ dukk auth status --json
$ dukk auth list

$ dukk send "como rodar os testes do workspace?"
$ dukk send --wait --json "explique isto"
$ cat erro.log | dukk send --stdin

$ dukk chat show --last 5
$ dukk chat show --json

$ dukk model get
$ dukk model set claude-opus-4-6

$ dukk reply "sim, pode prosseguir"
$ echo "opção 2" | dukk reply --stdin

$ dukk status
$ dukk status --json

$ dukk init
$ dukk init --embed-provider ollama --ollama-url http://localhost:11434
$ dukk init --backend qdrant --start-qdrant --qdrant-port 7333

$ dukk stats --days 30 --by-model
$ dukk stats --by-project

$ dukk agents
$ dukk agents <args>

$ dukk skills

$ dukk system-prompt --cwd . --date

$ dukk verify

$ dukk update

$ dukk uninstall

$ dukk --resume sessao.json

$ dukk dump-manifests

$ dukk bootstrap-plan

Modo interativo (TUI)

Sem subcomando, o dukk abre uma TUI ratatui (REPL interativa). Use --no-tui para forçar o REPL em modo texto. Os atalhos abaixo valem na entrada principal da TUI (fonte: tui.rs, input.rs, app.rs).

Modo vim do REPL inline

A entrada do REPL tem um modo vim opcional (fonte: input.rs), alternado pelo comando /vim (mostra "Vim mode enabled/disabled"). Quando ativo, o prompt exibe o modo entre colchetes (ex.: [INSERT] ›). Modos: INSERT, NORMAL, VISUAL e COMMAND (ex-mode com :).

• NORMAL: h j k l (mover), i (insert), v (visual), : (command), dd (apaga a linha), yy (copia a linha), p (cola).
• VISUAL: h j k l ajustam a seleção; v volta ao NORMAL.
• INSERT: texto normal; Esc volta ao NORMAL; Shift+Enter/Ctrl+J inserem nova linha.

SWD (Strict Write Discipline)

Camada de disciplina de escrita do Dukk (fonte: swd.rs). Controlada pela flag global --swd off|partial|full. O default é full.

Os estados de resultado registrados são Verified (mudou e o hash confere), Noop (sem mudança), Drift (hash divergente), Failed e RolledBack. Cada transação é gravada em JSON Lines no audit log:

# Audit log (relativo ao cwd)
.dukk/swd.log

# Uma linha JSON por ação
{"ts":1234567890,"tool":"swd_full","path":"src/foo.rs","outcome":"Verified","before":"abc123…","after":"def456…"}

Variáveis de ambiente

Principais variáveis lidas pelo runtime. Muitas existem em par DUKK_* / ELAI_* (ver nota de aliasing abaixo).

Providers

São 7 clientes HTTP reais (fonte: api/src/providers/). Anthropic tem cliente próprio; os demais usam a camada OpenAI-compat.

Slash commands

Disponíveis dentro da REPL/TUI interativa, digitando / seguido do comando. O sufixo [resume] indica que o comando também funciona com --resume SESSION.json. Catálogo completo (39 comandos), agrupado por categoria.

Os 39 comandos acima são os registrados em SLASH_COMMAND_SPECS. /collection e /unlock são extras ocultos (não listados no catálogo).