> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Instale a CLI do MKA1 Code, abra sessões interativas e execute tarefas em scripts.

export const ScreenshotCrop = ({src, alt, width, height, x = 0, y = 0, cropWidth = width, cropHeight = height, maxWidth = "100%"}) => <div className="not-prose" style={{
  position: "relative",
  overflow: "hidden",
  width: "100%",
  maxWidth,
  margin: "0 auto",
  aspectRatio: `${cropWidth} / ${cropHeight}`
}}>
    <img src={src} alt={alt} width={width} height={height} style={{
  position: "absolute",
  display: "block",
  margin: 0,
  maxWidth: "none",
  width: `${width / cropWidth * 100}%`,
  height: "auto",
  left: `${-x / cropWidth * 100}%`,
  top: `${-y / cropHeight * 100}%`
}} />
  </div>;

A CLI do MKA1 Code executa o agente de programação no terminal. Seu executável é `mka1-code`; a [CLI da MKA1 API](/pt/docs/cli/introduction) usa `mka1` para chamar operações da API.

## Instale a CLI

No macOS, no Linux ou no WSL, execute o script de instalação em um terminal:

```bash Bash theme={null}
curl -fsSL https://downloads.mka1.com/code/install.sh | bash
```

O script escolhe o build para o seu processador, verifica o checksum e instala o `mka1-code` em `~/.local/bin` sem `sudo`. Ele não altera a configuração do seu shell. Se essa pasta não estiver no seu `PATH`, o script mostra uma linha `export PATH` para adicionar ao arquivo de inicialização do shell, como `~/.zshrc` para Zsh ou `~/.bashrc` para Bash.

Abra um novo terminal e confirme que a CLI funciona:

```bash CLI theme={null}
mka1-code --version
```

Para atualizar a CLI, execute o script de instalação novamente. Para instalá-la em outra pasta, defina `MKA1_INSTALL_DIR`:

```bash Bash theme={null}
curl -fsSL https://downloads.mka1.com/code/install.sh | MKA1_INSTALL_DIR="$HOME/bin" bash
```

### Instale um pacote baixado

No Windows, ou para instalar a distribuição da sua organização, baixe o pacote de CLI e instale-o manualmente. Para uma distribuição da organização, siga as [etapas de download da organização](/pt/docs/mka1-code/install#distribuições-de-organizações) e escolha o pacote de CLI. Nos demais casos, baixe o pacote para seu sistema operacional e processador. Estes links correspondem ao MKA1 Code 1.57.4.

| Plataforma | Baixar |
| - | - |
| macOS · Apple silicon | [Baixar CLI](https://downloads.mka1.com/code/v1.57.4/mka1-code-cli-1.57.4-darwin-arm64) |
| macOS · Intel | [Baixar CLI](https://downloads.mka1.com/code/v1.57.4/mka1-code-cli-1.57.4-darwin-x64) |
| Windows · x64 | [Baixar CLI](https://downloads.mka1.com/code/v1.57.4/mka1-code-cli-1.57.4-win32-x64.exe) |
| Linux · ARM64 | [Baixar CLI](https://downloads.mka1.com/code/v1.57.4/mka1-code-cli-1.57.4-linux-arm64) |
| Linux · x64 | [Baixar CLI](https://downloads.mka1.com/code/v1.57.4/mka1-code-cli-1.57.4-linux-x64) |

<Tabs>
  <Tab title="macOS / Linux">
    Abra um terminal na pasta do executável baixado. Substitua `<downloaded-file>` pelo nome exato e copie o arquivo para um diretório de comandos do seu usuário:

    ```bash CLI theme={null}
    mkdir -p "$HOME/.local/bin"
    cp "<downloaded-file>" "$HOME/.local/bin/mka1-code"
    chmod +x "$HOME/.local/bin/mka1-code"
    export PATH="$HOME/.local/bin:$PATH"
    mka1-code --help
    ```

    O último comando deve mostrar a ajuda da CLI. O `export` vale apenas para o terminal atual. Para usar a CLI em novos terminais, adicione a mesma linha `export PATH` ao arquivo de inicialização do shell, como `~/.zshrc` para Zsh ou `~/.bashrc` para Bash.
  </Tab>

  <Tab title="Windows">
    1. Crie uma pasta para a CLI, como `%LOCALAPPDATA%\MKA1Code\bin`.
    2. Mova o executável baixado para essa pasta e renomeie o arquivo como `mka1-code.exe`.
    3. Adicione a pasta à variável de ambiente `Path` do seu usuário e abra uma nova janela do PowerShell.
    4. Execute `mka1-code --help`. O comando deve mostrar a ajuda da CLI. Se o comando não for encontrado, confira se `Path` contém a pasta, não o caminho completo do executável.
  </Tab>
</Tabs>

## Faça login e inicie uma sessão

Depois de instalar o executável, abra um terminal no diretório do projeto, faça login e inicie uma sessão interativa:

```bash CLI theme={null}
mka1-code login
mka1-code doctor
mka1-code
```

Confira os resultados individuais de `doctor` antes de começar. Ele identifica problemas de conta, catálogo de modelos, ambiente de execução e conectores.

Descreva a tarefa no terminal, acompanhe o progresso e responda às perguntas ou solicitações de aprovação. Use `/model` para selecionar um modelo, `@` para referenciar arquivos do projeto, `/attach <caminho>` para anexar uma imagem e `/sessions` para encontrar trabalhos anteriores. Use `/help` para ver os comandos interativos disponíveis.

Para retomar o trabalho, encontre o identificador com `/sessions` e informe-o em `--resume`:

```bash CLI theme={null}
mka1-code --resume <id-da-sessao>
```

<Frame caption="A saída de /help lista comandos para agentes, acesso à conta, consumo, plugins e diagnóstico.">
  <ScreenshotCrop src="/images/mka1-code/guides/cli.jpg" alt="Ajuda da CLI com os comandos disponíveis" width={1265} height={712} x={30} y={50} cropWidth={900} cropHeight={360} maxWidth="100%" />
</Frame>

## Execute uma tarefa em um script

Para executar uma tarefa única, use `run`:

```bash CLI theme={null}
mka1-code run "Leia README.md e identifique como executar este projeto e seus testes. Não altere arquivos."
```

Adicione `--output-format json` quando outro programa precisar consumir o resultado. A CLI retorna um objeto de resultado quando a execução termina:

```bash CLI theme={null}
mka1-code run --output-format json "Leia checkout.js e explique como as quantidades dos itens afetam o total. Não altere arquivos."
```

Uma execução não interativa não consegue responder a perguntas ou pedidos de aprovação. A CLI recusa solicitações que exigem essa interação, em vez de aguardar indefinidamente. Use uma sessão interativa para tarefas que precisam das suas decisões. Scripts devem conferir o status do resultado e o código de saída antes de considerar a tarefa bem-sucedida.

## Encontre modelos e sessões anteriores

Fora da interface interativa, use:

```bash CLI theme={null}
mka1-code whoami
mka1-code models --refresh
mka1-code sessions
```

`whoami` identifica a conta ativa. `models --refresh` atualiza o catálogo. `sessions` lista sessões recentes; adicione `--all` para incluir antigas ou `--json` para saída estruturada. Use o ID exibido com `--resume` para continuar a conversa correta.

No modo interativo, `/plan` controla o planejamento e `/permissions` a política de aprovação. `/compact` resume o histórico e `/usage` mostra consumo. `Ctrl + C` para o turno ativo; sem um turno, a CLI pergunta se você quer sair. `/exit` fecha a interface.

## Escolha o formato de saída

| Formato | Comportamento | Uso |
| - | - | - |
| `text` | Imprime a resposta como texto. | Ler no terminal. |
| `json` | Escreve um objeto ao terminar. | Processar uma tarefa concluída. |
| `stream-json` | Emite um registro JSON por linha durante a execução e um resultado final. | Acompanhar progresso em outro programa. |

Erros de diagnóstico vão para a saída de erro padrão. Separe-os da saída estruturada em scripts. Uma resposta final não prova que os testes passaram: examine o estado da tarefa e o resultado do comando.

Para um prompt salvo em arquivo, use a entrada padrão:

```bash CLI theme={null}
mka1-code run - < task.txt
```

Inclua em `task.txt` a solicitação completa, as premissas do projeto e a saída esperada. Execute no diretório do projeto.

Continue com [Consumo e solução de problemas](/pt/docs/mka1-code/troubleshooting).