---
title: "CLI"
description: "A linha de comando do Beeuni, seu modelo de autenticação, o ciclo de desenvolvimento e todos os comandos."
---

A interface de linha de comando (CLI) do `beeuni` controla o Beeuni pelo terminal — no seu laptop ou em um ambiente de sessão isolado. Esta página mostra o ciclo de desenvolvimento do dia a dia e, em seguida, lista todos os comandos e sinalizadores estáveis.

<a id="install"></a>

## Instalação

```sh
curl -fsSL https://beeuni.ai/install | bash
```

O instalador baixa um binário pré-compilado para macOS e Linux. O Windows não é compatível.

| Comando | Efeito |
| --- | --- |
| `beeuni update` | Executa novamente o script de instalação e baixa o binário mais recente. |
| `beeuni uninstall [-y\|--yes] [--keep-auth] [--keep-home]` | Remove o binário, o shim `/usr/local/bin` e o token armazenado. `--keep-auth` mantém o token. `--keep-home` mantém `~/.beeuni`. |
| `beeuni version` | Exibe a versão da CLI. |

<a id="auth-model"></a>

## Modelo de autenticação

O Beeuni armazena a autenticação por host, não globalmente. Um host é um endpoint da API do Beeuni. Use `cloud` para se conectar ao Beeuni.

O arquivo de configuração fica em `~/.config/beeuni/config.json`, no modo `0600`. Substitua o caminho com `BEEUNI_CONFIG_FILE`.

A CLI segue esta hierarquia: host → conta → projeto → sessão. Você entra em um host, escolhe uma conta dentro dele, escolhe um projeto nessa conta e abre sessões no projeto. `beeuni hosts login` percorre as três primeiras etapas nessa ordem: autentica você, escolhe a conta e, em seguida, define um projeto padrão.

Todos os tokens começam com `beeuni_pat_`. Um token de usuário, obtido com `beeuni login`, dá acesso a todas as contas e projetos dos quais você faz parte. Um token de projeto é gerado automaticamente para um ambiente de sessão isolado e tem escopo limitado a um único projeto. Consulte [Escopo do token](#token-scope).

<a id="the-dev-loop"></a>

## Ciclo de desenvolvimento

Este ciclo pressupõe que a CLI está instalada e que você executou `beeuni login`. Consulte [Início rápido](/docs/pt/quickstart) para configurar.

1. **Vincular um repositório**

    Inicie um projeto novo ou vincule a ele uma pasta de repositório existente.

    Para criar a estrutura de um projeto novo:

    ```sh
    beeuni init my-app
    cd my-app
    ```

    `beeuni init` cria um diretório de projeto com o modelo inicial de uso geral. Seu
    `beeuni.yaml` declara `beeuni_version: 2` e executa o [harness](/docs/pt/work/harnesses) do runtime padrão.

    Para vincular um repositório clonado existente a um projeto que você já criou:

    ```sh
    beeuni projects link <project-id>
    ```

    Este comando grava `.beeuni/link.json` no diretório atual. O Beeuni lê esse arquivo para localizar seu projeto sempre que um comando é executado a partir desta pasta. Se você pretende executar `beeuni ship` primeiro, pule esta etapa. Esse comando vincula um novo projeto para você, caso ainda não exista um.

2. **Envie seu código**

    ```sh
    beeuni ship
    ```

    `beeuni ship` analisa seu `beeuni.yaml`, faz commit das alterações locais, envia sua branch e solicita os segredos ou conexões que estiverem faltando. Execute-o sempre que quiser que suas alterações locais cheguem ao projeto na nuvem. Na primeira execução, ele também cria o projeto e o repositório na nuvem, caso você ainda não tenha vinculado um.

3. **Executar e conectar-se a sessões**

    Inicie uma sessão com um prompt:

    ```sh
    beeuni sessions new --prompt "Build the login page" --wait
    ```

    Cada sessão é executada em seu próprio ambiente isolado e em sua própria branch. `--wait` aguarda até que a sessão esteja pronta.

    Conecte-se a uma sessão pelo terminal:

    ```sh
    beeuni connect
    ```

    Sem o ID da sessão, `beeuni connect` (alias: `attach`) abre um seletor de sessões
    para o projeto vinculado — sessões em execução são conectadas imediatamente, as que foram interrompidas são inicializadas primeiro e `+ New session` inicia um novo ambiente isolado — e então abre a TUI completa do runtime padrão conectada a essa sessão. Passe um ID para pular o seletor:
    `beeuni connect <session-id>`.

    A CLI gerencia o binário `opencode` para você: na primeira conexão, baixa
    a versão exata usada pelo servidor da sessão e a armazena em cache em
    `~/.beeuni/opencode/<version>/`, para que a TUI e o servidor estejam sempre na mesma versão. Defina
    `BEEUNI_OPENCODE_BIN` para usar seu próprio binário.

    Uma sessão no [harness](/docs/pt/work/harnesses) do pi não tem servidor do runtime padrão.
    `beeuni connect` sai com o código 1 nesse caso e exibe a mensagem `O runtime desta sessão
    não é compatível com a conexão de um cliente de terminal.`

    Para conversar em um formato mais leve, baseado em linhas, em vez de usar a TUI completa, execute:

    ```sh
    beeuni sessions chat
    ```

    Isso abre um chat interativo com sua sessão mais recente. Adicione um ID para escolher uma sessão específica: `beeuni sessions chat <id>`.

    Para usar o produto inteiro no terminal — a lista de sessões, a transcrição e o campo de composição, um shell no ambiente isolado e as telas Arquivos, Revisão, Apps, Personalizar e Conta — execute o cliente de terminal experimental:

    ```sh
    beeuni tui        # or: beeuni t, or beeunit
    beeunit --project <id> --new --terminal   # new session + sandbox shell, one command
    ```

    Ele entra usando o host ao qual você já está conectado. Consulte [a página da TUI](/docs/pt/cli#sessions).

    Para abrir um shell direto no ambiente isolado, sem envolver um agente, execute:

    ```sh
    beeuni sessions shell
    ```

    Liste suas sessões em execução a qualquer momento:

    ```sh
    beeuni sessions ls
    ```

4. **Revisar com solicitações de alteração**

    Um agente abre uma solicitação de alteração (CR) quando a sessão tem commits prontos para mesclagem. Liste, inspecione e mescle solicitações pela CLI.

    ```sh
    beeuni cr ls
    beeuni cr diff 1
    beeuni cr merge 1
    ```

    `beeuni cr ls` lista as solicitações de alteração do projeto vinculado. `beeuni cr diff <cr>` exibe o patch unificado. `beeuni cr merge <cr>` mescla a solicitação na branch padrão do projeto. Aceite um número de CR ou seu ID completo.

<a id="reference"></a>

## Referência

<a id="auth-commands"></a>

### Comandos de autenticação

| Comando | Efeito |
| --- | --- |
| `beeuni login [--host <name>] [--api <url>] [--token <pat>] [--account <slug>] [--no-project]` | Entra no host ativo ou no host especificado. Por padrão, abre um navegador; `--token` autentica sem interface gráfica. `--no-project` ignora a escolha do projeto padrão. |
| `beeuni logout [--host <name>]` | Remove o token do host ativo ou do host especificado. |
| `beeuni whoami [--host <name>] [--json] [--token-only]` | Exibe o usuário conectado e a conta ativa. |
| `beeuni token [--host <name>]` | Atalho para `beeuni whoami --token-only`. |

`beeuni hosts login` / `hosts logout` / `hosts whoami` são as formas canônicas. `login` / `logout` / `whoami` são atalhos que atuam no host ativo.

### Hosts

| Comando | Efeito |
| --- | --- |
| `beeuni hosts ls [--json]` | Lista todos os hosts e o status de autenticação de cada um. |
| `beeuni hosts login [<name>] [--token <pat>] [--api <url>] [--account <slug>] [--no-project]` | Entra em um host. Se o nome for desconhecido, primeiro registra o host. |
| `beeuni hosts logout [<name>]` | Remove o token de um host. |
| `beeuni hosts use <name>` | Alterna o host ativo. |
| `beeuni hosts add <name> --url <url> [--dashboard-url <url>] [--login]` | Registra um novo host. `--login` também faz login logo em seguida. |
| `beeuni hosts rm <name> [--force]` | Remove um host. |
| `beeuni hosts info [<name>] [--json]` | Exibe os detalhes de um host. |
| `beeuni hosts current [--json]` | Exibe o nome do host ativo. |

Uma URL de host remoto que começa com `http://` é normalizada para `https://`. A CLI nunca envia um token por HTTP sem criptografia a um host remoto. `localhost` é uma exceção.

<a id="accounts"></a>

### Contas

| Comando | Efeito |
| --- | --- |
| `beeuni accounts ls [--json]` | Lista as contas das quais você faz parte no host ativo. |
| `beeuni accounts use [<slug-or-id>]` | Alterna a conta ativa. |
| `beeuni accounts current [--json]` | Exibe a conta ativa. |
| `beeuni accounts info [<slug-or-id>] [--json]` | Exibe uma conta. |

<a id="members"></a>

### Membros

Quem faz parte da conta e qual função cada pessoa tem nela. As funções são `owner`,
`admin` e `member`. Proprietários e administradores têm implicitamente a função Manager em todos os projetos, portanto `member` é a única função que exige concessões por projeto.

| Comando | Efeito |
| --- | --- |
| `beeuni members ls [--json]` | Lista membros, funções e quantidade de projetos. |
| `beeuni members invite <email> --role admin\|member [--project <id>:<role>]` | Convida por e-mail. Um usuário existente do Beeuni é adicionado imediatamente; qualquer outra pessoa recebe um link de convite por e-mail. `--project` pode ser usado repetidamente e é aplicado quando o convite é aceito. Requer `member.invite`. |
| `beeuni members set-role <user\|email> --role owner\|admin\|member` | Altera a função de uma conta. Requer `member.update`; somente o proprietário pode atribuir a função `owner`. |
| `beeuni members rm <user\|email> [-y\|--yes]` | Remove um membro e revoga seus tokens. Requer `member.remove`. |
| `beeuni members super-admin <user\|email> on\|off` | Concede ou revoga a exceção de superadministrador. Requer `member.super_admin.grant`. |
| `beeuni members invites ls [--json]` | Lista os convites pendentes que você enviou. |
| `beeuni members invites cancel <invite-id>` | Cancela um convite pendente. |
| `beeuni members invites resend <invite-id>` | Reenvia o e-mail e renova o prazo de validade de 14 dias. |

Um `<user>` é um ID de usuário ou o e-mail de alguém que já faz parte da conta.
Opções: `--account <id>`, `--host <name>`, `--json`, `-y`.

<a id="groups"></a>

### Grupos

Um grupo de contas é um conjunto nomeado de pessoas às quais você atribui uma função uma única vez. Vincule um
grupo a um escopo com `beeuni access grant --group <id> --role <key>`; revogue
com `beeuni access revoke <assignment-id>`.

| Comando | Efeito |
| --- | --- |
| `beeuni groups ls [--json]` | Lista grupos com as contagens de membros e projetos. |
| `beeuni groups create <name> [--description <t>]` | Cria um grupo. |
| `beeuni groups set <group> [--name <n>] [--description <t>\|--no-description]` | Renomeia ou altera a descrição de um grupo. |
| `beeuni groups rm <group> [-y\|--yes]` | Exclui um grupo. Suas concessões são excluídas com ele. |
| `beeuni groups members <group> [--json]` | Lista os membros de um grupo. |
| `beeuni groups add <group> <user>...` | Adiciona uma ou mais pessoas. |
| `beeuni groups remove <group> <user>` | Remove uma pessoa. |
| `beeuni groups projects <group> [--json]` | Mostra quais projetos o grupo acessa e com qual função. |

Um `<group>` é um ID de grupo ou seu nome exato. As leituras precisam de `group.read`.
`create`, `set` e `add` precisam de `group.update` ou `group.members.manage`, além
do entitlement empresarial `rbac`. `rm` e `remove` são operações de limpeza e nunca
são condicionados a entitlement.

### Tokens

Credenciais não interativas para a conta. As leituras precisam de `token.read`. Todo
membro da conta pode criar e revogar suas próprias chaves pessoais
(`token.personal.create`, `token.personal.revoke`); uma chave pessoal age como você
e nunca carrega mais do que suas próprias funções. Contas de serviço e chaves de outras pessoas
precisam de `token.create` / `token.revoke` (proprietário e administrador).

| Comando | Efeito |
| --- | --- |
| `beeuni tokens ls [--mine] [--json]` | Lista as chaves de API pessoais da conta. `--mine` restringe a lista às chaves criadas por você. |
| `beeuni tokens new <name> [--expires <when>] [--project <id>]` | Cria uma chave. O segredo é exibido uma única vez. `--project` a vincula a um projeto, do qual ela nunca poderá sair. |
| `beeuni tokens rm <token-id> [-y\|--yes]` | Revoga uma chave imediatamente. |
| `beeuni tokens apps ls [--json]` | Lista seus aplicativos conectados: os aplicativos e clientes MCP que você aprovou com Sign in with Beeuni, em todas as contas. |
| `beeuni tokens apps rm <client-id> [-y\|--yes] [--json]` | Revoga um aplicativo conectado: os tokens dele param de funcionar imediatamente, e ele precisa solicitar sua aprovação novamente. |
| `beeuni tokens service-accounts ls [--json]` | Lista as contas de serviço. |
| `beeuni tokens service-accounts new <name> [--description <t>] [--expires <when>]` | Cria uma. O bearer é exibido uma única vez. |
| `beeuni tokens service-accounts disable <id>` | Desativa uma conta de serviço: ela não pode mais autorizar; exclua e recrie para reativá-la. |
| `beeuni tokens service-accounts rm <id> [-y\|--yes]` | Exclui uma conta de serviço permanentemente. |

Uma chave de API pessoal age como você e deixa de funcionar quando sua associação termina. Uma conta
de serviço age como si mesma e não herda nenhum acesso: uma nova não tem permissões.
Conceda uma permissão a ela com `beeuni access grant --service-account <id> --role <key>`.
`--expires <when>` aceita ISO-8601 ou um período futuro: `30d`, `12h`, `6w`, `1y`.

<a id="billing"></a>

### Faturamento

Leia o plano, os créditos e os gastos da conta ativa. Somente leitura: alterações de plano,
recargas e formas de pagamento são fluxos do painel.

| Comando | Efeito |
| --- | --- |
| `beeuni billing status [--json]` | Plano, créditos, assentos e assinatura. |
| `beeuni billing transactions [--limit <n>] [--offset <n>] [--type <a,b>] [--json]` | Livro-razão de créditos, do mais recente para o mais antigo. Tamanho padrão da página: 50. |
| `beeuni billing transactions --summary\|--breakdown\|--usage [--days <n>]` | Entradas/saídas de créditos, divisão do saldo (expirando/não expirando/diário) ou um resumo do uso de créditos. `--days` é a janela para `--summary` e `--usage`; o padrão é 30. |
| `beeuni billing costs [--since <iso>] [--until <iso>] [--json]` | Gastos da conta em uma janela, além de uma divisão por modelo. Janela padrão: 30 dias, `[from, to)` UTC semiaberta. |
| `beeuni billing costs --by project\|session [--sort <k>] [--limit <n>] [--offset <n>] [--csv <file>]` | Consolida os gastos por projeto ou por sessão. `--sort` aceita `total_desc` (padrão), `total_asc`, `recent` ou `name_asc` (somente `--by project`). `--csv` precisa de `--by`. |

Filtros: `--project <id>`, `--session <id>` e `--owner <id>` (sessões, com
`--by session`). Opções: `--account <id>`, `--host <name>`, `--json`.

<a id="projects"></a>

### Projetos

Um comando resolve "o projeto" nesta ordem:

1. A flag `--project`.
2. A variável de ambiente `BEEUNI_PROJECT_ID`.
3. `.beeuni/link.json` no diretório de trabalho exato.
4. O padrão global definido por `beeuni projects use`.

| Comando | Efeito |
| --- | --- |
| `beeuni projects ls [--all] [--query <text>] [--json]` | Lista os projetos da conta ativa. `--all` abrange todas as contas às quais você pertence. `--query` (alias `-q`) filtra por nome, ID ou repositório. |
| `beeuni projects info [<id>] [--json]` | Mostra um projeto. Padrão: o projeto vinculado ou padrão. |
| `beeuni projects use [<id>]` | Define o projeto padrão global. Alterna a conta ativa se o projeto estiver em outro local. |
| `beeuni projects unset` | Limpa o projeto padrão global. |
| `beeuni projects link [<id>]` | Vincula o diretório atual a um projeto. Grava `.beeuni/link.json`. |
| `beeuni projects unlink` | Remove `.beeuni/link.json`. |
| `beeuni projects open [<id>]` | Abre a página do painel de um projeto no navegador. |
| `beeuni projects clone [<id>] [dir]` | Clona o repositório de um projeto pelo proxy git autenticado da Beeuni. |
| `beeuni projects rm [<id>] [-y\|--yes]` | Exclui um projeto e seu repositório git gerenciado pela Beeuni. Repositórios conectados por você nunca são alterados. |
| `beeuni projects set [<id>] [--name <n>] [--branch <b>] [--manifest <path>] [--json]` | Atualiza as configurações de um projeto. Somente os campos informados são gravados. Não informar nenhum campo encerra `2`. Alias: `update`. |
| `beeuni projects set [<id>] --icon <emoji>\|--no-icon\|--glyph <name>:<color>\|--no-glyph` | Define ou remove o ícone do projeto. |
| `beeuni projects rename [<id>] <name>` | Alias de `beeuni projects set --name <name>`. |
| `beeuni projects features [ls] [--json]` | Lista todas as flags de recurso com sua chave, estado, origem e estabilidade. |
| `beeuni projects features enable\|disable\|reset <flag>` | Ativa ou desativa a substituição do projeto, ou a limpa para que a flag siga o padrão da plataforma. |
| `beeuni projects cli-tokens ls [--json]` | Lista os tokens de CLI do projeto. |
| `beeuni projects cli-tokens new [--name <name>] [--expires-at <iso>]` | Cria um token de CLI com escopo de projeto. O segredo é exibido uma única vez. |
| `beeuni projects cli-tokens rm <token-id> [-y\|--yes]` | Revoga um token de CLI do projeto. |
| `beeuni projects upgrade [<id>] [--json]` | Inicia a sessão do agente que migra um `beeuni.toml` v1 para um `beeuni.yaml` v2 e abre uma solicitação de alteração. |

Um projeto exibe um único ícone; portanto, escrever `--icon` limpa o glifo, e escrever
`--glyph` limpa o emoji; informar ambos é recusado. Cores dos glifos: `grey`,
`red`, `orange`, `yellow`, `lime`, `blue`, `purple`, `magenta`. `set` e
`features` precisam de `project.settings.write`. Uma flag marcada pela plataforma
como indisponível permanece desativada independentemente da substituição do projeto.

Um token de CLI de projeto é vinculado a um único projeto — a API o rejeita em qualquer outro local.
Um sandbox de sessão usa seu `BEEUNI_TOKEN` vinculado à sessão. `cli-tokens ls`
precisa de acesso de leitura ao projeto; `new` e `rm` precisam de
`project.credentials.issue`. Um token vinculado à sessão não pode criar nem
revogar tokens do projeto (`403`), independentemente de o projeto declarar agentes. Um
token de CLI de projeto segue a política de PAT da conta: quando a conta exigir
expiração, informe `--expires-at`; uma expiração além do tempo de vida máximo retorna
`400`.

`beeuni projects upgrade` precisa de acesso de gravação ao projeto. O agente padrão atualiza a
linha de base do marketplace, reescreve o manifesto, executa `beeuni validate` e abre
uma solicitação de alteração. Ele nunca faz merge: uma pessoa revisa o diff.

<a id="project-scaffold"></a>

### Estrutura do projeto

`beeuni init [project-name] [options]` cria um novo diretório de projeto. O
starter grava um `beeuni.yaml` v2, `agents/`, `skills/`, `memory/` e
`harnesses/opencode/`. O comando pode configurar a descoberta local de ferramentas de
codificação sem alterar o runtime padrão na nuvem. O comando não grava
`.beeuni/link.json`. `beeuni ship` ou `beeuni projects link` criam esse arquivo.

| Flag | Significado |
| --- | --- |
| `--name <project>` | Nome do projeto. |
| `--primary <agent>` | Agente principal. |
| `--agents <csv>` | Integrações locais de agentes de codificação a configurar. |
| `--force` | Configura o diretório atual no local, em vez de criar uma nova estrutura. |
| `--overwrite` | Substitui arquivos existentes. |
| `--no-git` | Ignora a inicialização do git. |
| `-y, --yes` | Não solicita confirmação. |

A seleção da ferramenta local de codificação não altera o runtime padrão na nuvem.

`beeuni init` não inclui um seletor de marketplace. Adicionar uma skill do marketplace é uma importação de agente: inicie uma sessão e peça ao agente para trazê-la.

<a id="ship"></a>

### Envio

`beeuni ship` prepara, faz commit e envia sua branch atual para o repositório git do projeto. Execute uma vez para criar o projeto. Execute novamente a qualquer momento para sincronizar. Alias: `beeuni deploy`.

Cada execução:
- Executa as verificações de [`beeuni validate`](#manifest-validation): `beeuni.yaml` mesclado com cada arquivo listado em [`imports:`](/docs/pt/project/manifest#imports), Dockerfiles do sandbox, configuração do agente e tamanho do repositório (ignore com `--no-verify`). Um erro interrompe a publicação. Um aviso nunca interrompe.
- Faz commit de quaisquer alterações na árvore de trabalho (ignore com `--no-commit`).
- Solicita qualquer segredo `env` ausente (ignore com `--no-env`).
- Envia a branch atual para a branch remota de mesmo nome.
- Conecta qualquer conector declarado que ainda precise de autenticação (ignore com `--no-connect`).

Um `origin` existente do GitHub se conecta por meio do Beeuni GitHub App. Qualquer outro `origin` existente é registrado como está. Sem `origin`, um repositório Git gerenciado pelo Beeuni é criado.

| Opção | Efeito |
| --- | --- |
| `--name <project>` | Nome de exibição de um projeto novo. |
| `--account <id\|slug>` | Conta na qual criar o projeto (somente na primeira publicação). |
| `--origin <managed\|git-url>` | Substitui a escolha de origem inferida. |
| `--github-token <pat>` | Conecta uma origem do GitHub com este token, em vez de usar o GitHub App. |
| `-m, --message <text>` | Mensagem do commit. |
| `--no-commit` / `--no-verify` / `--no-env` / `--no-connect` | Ignora essa etapa. |
| `-y, --yes` | Não solicita confirmação. |
| `-n, --dry-run` | Mostra o que aconteceria, sem alterar nada. |
| `--project <id>` / `--host <name>` | Define como destino um projeto ou host que não seja o padrão. |

### Apps

Apps hospeda sites estáticos, servidores, tarefas e bancos de dados. Cada App tem uma URL estável. Uma versão contém código e configuração; uma implantação com falha não substitui a versão ativa.

```bash
beeuni apps list
beeuni apps show main
beeuni apps connect main
beeuni apps launch --template convex --slug main
beeuni apps deploy dist --type static --spa
beeuni apps machines main
beeuni apps volumes main
```

Conecte Apps com `uses` e os exemplos de `beeuni apps connect`. Não inclua credenciais administrativas no código cliente.

Recursos ativos consomem créditos da conta. Consulte Billing e Usage. Apps não possui um orçamento mensal separado.

[Apps](/docs/feature-flags/apps)

### Sessões

Cada sessão é executada em um sandbox, em sua própria branch.

| Comando | Efeito |
| --- | --- |
| `beeuni sessions ls [--mine\|--shared\|--automated] [--search <q>] [--label <label>]... [--json]` | Lista as sessões. `--label` pode ser repetido; uma sessão precisa ter todos os rótulos informados. A coluna LABELS aparece quando alguma sessão listada tem rótulos. |
| `beeuni sessions status [--all] [--json]` | Todas as sessões e o que seus agentes estão fazendo no momento. Aliases: `overview`, `ps`. |
| `beeuni sessions info <id> [--json]` | Visualização detalhada: status, branch, agente, URL do sandbox. |
| `beeuni sessions new [--prompt "<text>"] [--agent <name>] [--model <id>] [--wait] [--connect] [--json]` | Inicia uma sessão. `--connect` conecta à TUI do runtime padrão quando ela estiver pronta (implica `--wait`); em um terminal interativo sem essa opção, a CLI pergunta se você quer se conectar após a criação. `--model <id>` substitui o modelo padrão do projeto; um modelo que usa uma chave de API ou uma assinatura do ChatGPT usa todas as chaves que você pode usar para ele, alternando entre elas. `--wait` aguarda até a sessão estar em execução (até ~5 minutos). Use `--secret <id>` ou `--no-secrets` para restringir o acesso a Secrets. Essas opções de Secret exigem um token de backend. Use `--connector <alias>=<authorization-id>` ou `--no-connectors` para definir o acesso a Connector. Use `--require-connector <alias>` para exigir autorização antes do provisionamento. As opções de escopo podem ser repetidas. Use `--context <key>=<value>` para contexto de execução não secreto. `--label <label>` (repetível) classifica a sessão; `--meta <key>=<value>` (repetível) armazena uma string nos metadados dela. |
| `beeuni sessions chat [<id>] [--prompt "<text>"] [--queue \| --steer] [--new] [--agent <name>] [--json]` | Converse com o agente de uma sessão. Interativo por padrão. Alias: `talk`. O comando de nível superior `beeuni chat` também funciona. `--queue` funciona apenas uma vez: armazena o prompt na caixa de entrada persistente da sessão e retorna assim que ele é armazenado, em vez de encaminhá-lo ao runtime. `--steer` armazena o prompt da mesma forma, e o turno em execução o lê na próxima etapa sem parar. Se não houver um turno em execução, inicia um. Uma sessão que não pode ser direcionada o executa como `--queue`. |
| `beeuni sessions connect [<id>] [-- <opencode args>]` | Conecta a TUI do runtime padrão ao servidor do runtime padrão da sessão. Também disponível no nível superior: `beeuni connect` / `beeuni attach`. Sem um ID, abre um seletor de sessão (em execução, parada com reinicialização disponível ou nova). A CLI baixa automaticamente o binário `opencode` correspondente à versão (cache: `~/.beeuni/opencode/<version>/`; substituição: `BEEUNI_OPENCODE_BIN`). Uma sessão pi não tem servidor opencode: o comando termina com `1` e indica `beeuni sessions shell` e `beeuni sessions chat` como alternativas. |
| `beeuni tui [--host <name>] [--project <id>] [--session <id>] [--new] [--agent <name>] [--terminal] [--no-sidebar] [--mouse] [--install] [--uninstall]` | **Experimental.** Abre o cliente de terminal Beeuni: sessões, transcrição, compositor, shell do sandbox, Files, Review, Apps, Customize e Account. Aliases `beeuni t` e `beeunit`. `--new` cria uma sessão no projeto durante a inicialização (`--agent` escolhe o agente), `--terminal` abre o shell do sandbox em foco, `--no-sidebar` inicia sem a barra lateral (`Alt+B` alterna a exibição), `--mouse` transfere o controle do mouse para o aplicativo (desativado por padrão para que a seleção, a cópia e os cliques em links do terminal continuem funcionando). A TUI é um binário separado de ~80 MB; na primeira execução, pergunta se você quer instalá-lo e então instala o `beeuni-tui` correspondente à versão em `~/.beeuni/tui/<version>/`; as atualizações posteriores da CLI o atualizam sem perguntar e reutilizam um binário que não mudou. `--install` faz isso sem perguntar, `--uninstall` o remove. Usa o host ativo, a menos que `--host` indique outro; se nenhum host estiver conectado, abre a própria tela de login. `?` mostra todos os atalhos de teclado. Consulte [/docs/cli#sessions](/docs/pt/cli#sessions). |
| `beeuni sessions shell [<id>] [--new]` | Abre um terminal interativo sem agente no sandbox. Reconecta ao terminal existente da sessão; `--new` sempre inicia um novo. Aliases: `terminal`, `ssh`. |
| `beeuni sessions shell <id> ls [--json]` | Lista os terminais da sessão: ID, status, comando. Não precisa de TTY. |
| `beeuni sessions shell <id> kill <pty-id>` | Encerra um terminal. O shell de ambiente é reiniciado na próxima conexão; o que estiver sendo executado dentro dele não é. |
| `beeuni sessions forward <id> --port <sandbox>[:<local>]` | Encaminha uma porta do sandbox para sua máquina, no estilo do VS Code, para que `http://localhost:3000` exibido por um agente funcione no seu próprio navegador. `--port` pode ser repetido; sem uma porta local, usa-se o mesmo número se estiver disponível; caso contrário, a próxima porta livre. `:0` solicita uma porta efêmera atribuída pelo sistema operacional. Encaminha HTTP e WebSocket (o hot reload do servidor de desenvolvimento funciona). Exibe uma linha `⇄ localhost:N → sandbox:M` por encaminhamento e permanece em primeiro plano até Ctrl+C. Não inicia uma sessão parada — em vez disso, exibe a solução `beeuni sessions restart`. Alias: `ports`. |
| `beeuni sessions log [<id>] [--limit <n>] [--json]` | Exibe as mensagens recentes, somente para leitura. Uma sessão em execução é lida em tempo real; uma sessão parada é lida na transcrição salva ao fim de cada turno, portanto nunca é reativada apenas para ser lida. A origem é indicada em stderr, então a saída de `--json` permanece inalterada. Aliases: `messages`, `history`. |
| `beeuni sessions attachments <id> [--download <attachment-id>\|--all] [--out <dir>] [--json]` | Lista os arquivos armazenados da sessão — o que os usuários anexaram e cópias dos arquivos exibidos pelo agente — e os baixa. Funciona mesmo com a sessão parada: nem a lista nem os arquivos precisam estar no sandbox. Os downloads nunca sobrescrevem arquivos; se o nome já estiver em uso, ele passa a ser `name (1).ext`. |
| `beeuni sessions pending <id> [--json]` | Lista prompts pendentes de permissão de ferramenta ou de pergunta. Alias: `prompts`. |
| `beeuni sessions approve <id> [<req-id>] [--always] [--reject] [--message "<text>"]` | Responde a um prompt de permissão. |
| `beeuni sessions answer <id> [<req-id>] [--option <v>]... [--text "<text>"] [--reject]` | Responde a um prompt de pergunta. |
| `beeuni sessions digest [--since <7d>] [--json]` | Revisão compacta de várias sessões. A transcrição de uma sessão parada vem da cópia salva e é marcada como `saved` (e `partial` quando essa cópia não chega à primeira mensagem). Aliases: `review`, `summary`. |
| `beeuni sessions scope <id> [scope options] [--json]` | Lê ou substitui o acesso a Secret e Connector. Alias: `access`. Use `--secret <id>`, `--no-secrets` ou `--inherit-secrets` para Secrets. Use `--connector <alias>=<authorization-id>` ou `--no-connectors` para associações de Connector. Use `--require-connector <alias>` ou `--no-required-connectors` para Connectors obrigatórios. As categorias informadas substituem os valores atuais. As categorias omitidas permanecem inalteradas. As alterações se aplicam ao próximo prompt. Os valores de Secret removidos permanecem no contexto existente se a sessão já os tiver lido. |
| `beeuni sessions preview <id> [port] [--port <n>] [--list] [--json]` | Exibe uma URL de visualização clicável para uma porta do sandbox. Porta padrão: `3000`. `--list` exibe os candidatos nomeados. |
| `beeuni sessions restart <id>` | Reinicia o sandbox da sessão. |
| `beeuni sessions rename <id> <name>` | Define o nome de uma sessão. Passe `""` para removê-lo. |
| `beeuni sessions update [<id>] [--label <l>]... [--unlabel <l>]... [--clear-labels] [--meta <key>=<value>]... [--unmeta <key>]... [--json]` | Altera os rótulos e metadados de uma sessão. `--label` adiciona, `--unlabel` remove e `--clear-labels` esvazia a lista primeiro; `--meta` define uma chave de string, `--unmeta` remove uma chave. Sem um ID, atualiza `$BEEUNI_SESSION_ID`, permitindo que um agente rotule a sessão em que está sendo executado. Alias: `label`. |
| `beeuni sessions rm <id>...` | Para e exclui uma ou mais sessões. |
| `beeuni sessions open <id>` | Abre a página da sessão no painel, no navegador. |
| `beeuni sessions stop <id> [--json]` | Pausa uma sessão. O sandbox para no estado atual e o disco é mantido. Alias: `pause`. Requer `project.session.stop`. |
| `beeuni sessions start <id> [--wait] [--json]` | Reativa uma sessão: provisiona um sandbox ausente, retoma um parado e resolve o runtime. É idempotente. Alias: `wake`. `--wait` aguarda até que esteja pronta (até ~5 min) e termina com `1` se a sessão acabar com falha ou parada. |
| `beeuni sessions warm [--exclude <id>] [--json]` | Pré-cria a sessão que você está prestes a usar, para que o sandbox já esteja ativo. Reutiliza uma sessão aquecida existente que não esteja em uso. Uma sessão aquecida permanece oculta de `sessions ls` até o primeiro prompt. |
| `beeuni sessions model <id> <model-id> [--json]` | Altera o modelo usado por uma sessão durante a execução. Um sandbox ativo é redirecionado para o novo modelo e seu runtime é reiniciado, encerrando o turno em execução; uma sessão parada armazena o valor para a próxima inicialização. Uma sessão sem chaves selecionadas para o provedor do novo modelo recebe todas as chaves que você pode usar nele. |
| `beeuni sessions compact <id> [--json]` | Resuma a conversa até aqui e continue a partir do resumo. Uma sessão cujo runtime não liste `session.compact` é encerrada com `1` como motivo. |
| `beeuni sessions queue <id> [ls] [--json]` | Liste os prompts que ainda aguardam na caixa de entrada persistente da sessão. |
| `beeuni sessions queue <id> rm <prompt-id>` | Descarte um prompt na fila. A solicitação é recusada (`409`) assim que uma etapa do modelo começa a respondê-la. |
| `beeuni sessions queue <id> now <prompt-id>` | Execute em seguida um prompt da fila: coloque-o novamente na fila, à frente da regra de ordenação, e libere a pausa da sessão. |
| `beeuni sessions queue <id> hold\|release` | Coloque todos os prompts da fila em espera — o que o botão Stop faz — ou libere a espera. |
| `beeuni sessions approvals <id> [ls] [--json]` | Liste as chamadas de conectores controladas para as quais esta sessão está aguardando uma pessoa. |
| `beeuni sessions approvals <id> approve\|deny <execution-id>` | Permita ou recuse a execução de uma chamada de conector controlada. O agente será informado e continuará sem ela. |
| `beeuni sessions files <id> <subcommand> [--json]` | Leia e edite o workspace ativo do sandbox: `ls [<path>]`, `status`, `find <query>`, `write <path>`, `touch <path>`, `mkdir <path>`, `mv <from> <to>`, `rm <path>`. |
| `beeuni sessions share <id> [--mode private\|project\|members] [--member <id\|email>] [--group <id>] [--show] [--json]` | Defina quem dentro do Beeuni pode abrir esta sessão. Sem `--mode`, exibe a configuração atual e não altera nada. `--member` e `--group` podem ser repetidos. |
| `beeuni sessions links <id> ls [--json]` | Liste todos os links públicos já criados para a sessão, do mais recente ao mais antigo. |
| `beeuni sessions links <id> create [options]` | Crie um link público, sem autenticação, para uma porta de pré-visualização ou um arquivo do workspace. |
| `beeuni sessions links <id> revoke <share-id>` | Invalide um link público. |

`sessions queue` exige `project.session.start` — a mesma permissão necessária para enviar uma mensagem. Um prompt na fila persiste mesmo que o terminal seja fechado e é entregue quando a sessão puder recebê-lo. Coloque um na fila com `beeuni sessions chat <id> -p "…" --queue` ou direcione a execução em andamento com `--steer`. `sessions queue ls` mostra o `DELIVERY` de cada prompt (`steer`, `queue` ou `interrupt`) e, para um prompt de direcionamento executado como `queue`, o motivo: `unsupported` (a sessão não pode receber mensagens durante a execução), `not_prompter` (a execução de outro membro está em andamento) ou `turn_ended`.

`sessions approvals` são persistentes: ao contrário de `sessions pending`, sobrevivem à reinicialização do sandbox. É necessário ter `project.members.manage` ou ser a pessoa que iniciou a sessão. Um agente nunca pode resolver a própria aprovação.

`sessions attachments` lê o armazenamento privado de arquivos da sessão, não o workspace. Os arquivos são colocados lá no momento do envio, e todos os arquivos exibidos pelo agente são colocados lá ao final da execução.

`sessions files` lê a árvore de trabalho que o agente está editando no momento, antes de qualquer commit; `beeuni files` lê o repositório com commit. Os caminhos são resolvidos em `/workspace`, a menos que comecem com `/workspace`, `/tmp`, `/home` ou `/opt`. O comando ativa o sandbox se ele estiver inativo. Opções: `--from <local path>` (`write` lê este arquivo em vez da entrada padrão), `--content` (`find` pesquisa o conteúdo com ripgrep em vez dos nomes dos arquivos), `--limit <N>` (limite de nomes de arquivo `find`) e `-y` para ignorar a confirmação de `rm`.

`sessions share` é controlado pelo proprietário: a API recusa um gerente de projeto que ainda não tenha permissão para ler a sessão. Uma sessão compartilhada só é executada com chaves de provedor compartilhadas com todo o projeto: um modelo que usava suas próprias chaves passa a usar as chaves do projeto para esse provedor; se não houver nenhuma que o execute, o compartilhamento será recusado (`409 SHARED_SESSION_NEEDS_PROJECT_KEY`).

Opções de `sessions links create`: `--port <n>` (padrão `3000`; `22`, `8000` e as portas do opencode são recusados), `--path <p>` (padrão `/`), `--preview <id>` (um candidato nomeado — `web`, `vite`, `dev-server`, `api-docs` — em vez de `--port`/`--path`), `--file <path>` (compartilha um arquivo do workspace em vez de uma pré-visualização; sempre somente leitura), `--mode view\|interactive` (padrão `view`; `interactive` permite gravações e websockets e é ignorado para `--file`), `--label <text>` e `--expires <iso>`. A criação de um link exige o proprietário da sessão, pois o link não exige login; para listar e revogar, também é aceito um gerente de projeto.

Dentro de um sandbox, `BEEUNI_SESSION_ID` é o ID da sua própria sessão.

<a id="change-requests"></a>

### Solicitações de alteração

Uma solicitação de alteração (CR) integra uma ramificação a outra em qualquer host Git. É a única forma de um agente incorporar o trabalho da sessão à ramificação padrão. Consulte [Solicitações de alteração](/docs/pt/work/change-requests).

| Comando | Efeito |
| --- | --- |
| `beeuni cr ls [--status open\|merged\|closed\|all] [--project <id>]` | Liste CRs. Padrão: `--status open`. |
| `beeuni cr show <cr> [--project <id>]` | Mostre uma CR, incluindo a pré-visualização da integração. Alias: `info`. |
| `beeuni cr diff <cr> [--no-color] [--json]` | Exiba o diff unificado de uma CR. |
| `beeuni cr open --title "<text>" [--description "<text>"] [--head <ref>] [--session <id>] [--base <ref>]` | Abra uma CR. Aliases: `new`, `create`. Dentro de um sandbox, `--head` e `--session` são definidos automaticamente como padrão. `--base` usa como padrão a ramificação padrão do projeto. |
| `beeuni cr merge <cr> [--message "<text>"]` | Integre uma CR aberta. Faz fast-forward quando possível; caso contrário, uma integração de três vias. |
| `beeuni cr close <cr>` | Feche uma CR aberta sem integrá-la. |
| `beeuni cr reopen <cr>` | Reabra uma CR fechada. CRs integradas são definitivas. |
| `beeuni cr merge-preview <cr> [--json]` | Informe se a CR pode ser integrada e liste todos os caminhos com conflitos. Alias: `preview`. |
| `beeuni cr request-changes <cr> --message "<text>"` | Peça ao agente que abriu a CR para revisá-la. Alias: `changes`. |
| `beeuni cr version-diff --from <ver> --into <ver> [--json]` | Resuma uma versão em relação a outra antes de abrir uma CR. |

`request-changes` registra a observação na CR e a envia à sessão de origem, iniciando o sandbox se estiver inativo. Exige `project.review.act` — a mesma permissão específica usada pelo Centro de Revisão, não `gitops.push`.

`<cr>` aceita um número específico do projeto (`3`) ou o ID completo. Dentro de um sandbox, a CLI lê o token automaticamente — não é necessário fazer login nem usar um link.

<a id="review"></a>

### Revisão

A caixa de entrada de revisão do projeto — tudo que aguarda a decisão de uma pessoa: solicitações de alteração, chamadas de ferramentas de conectores cuja política exige aprovação e resultados, decisões e lotes enviados pelos agentes para aprovação. Corresponde ao Centro de Revisão do painel. Está ativada em todos os projetos; `project.review.read` e `project.review.act` controlam a leitura e a ação.

| Comando | Efeito |
| --- | --- |
| `beeuni review ls [--segment <s>] [--kind <k>] [--json]` | Liste os itens da caixa de entrada. Padrão: todos os segmentos. |
| `beeuni review show <item-id> [--json]` | Mostre um item por completo. |
| `beeuni review act <item-id> <verdict> [--message <text>]` | Decida sobre um item. `--message` inclui a observação. |
| `beeuni review bulk <verdict> <id> [<id> …]` | Decida sobre vários itens nativos em uma única chamada. |
| `beeuni review submit --kind <k> --title <t> [options]` | Envie um resultado, uma decisão ou um lote para revisão. |

Vereditos: `approve`, `reject`, `changes`, `answer`, `dismiss`. Segmentos: `needs_you`, `waiting`, `done`. Tipos: `change`, `approval`, `output`, `decision`, `batch`.

O destino de um veredito depende do ID do item. Em `cr:<id>`, `approve` integra a alteração, `reject` fecha a solicitação e `changes` envia a observação ao agente que a abriu (`--message` obrigatório). Em `call:<id>`, `approve` permite a execução da chamada de ferramenta e `reject` a recusa; uma aprovação de conector não aceita outro veredito — primeiro leia os argumentos com `beeuni review show`. Qualquer outro ID é enviado ao endpoint de ação nativo, que aceita todos os vereditos.

`bulk` age somente sobre IDs nativos. Uma aprovação de conector exige a revisão dos parâmetros, e uma solicitação de alteração exige que o diff esteja visível; por isso, ambas são informadas e ignoradas — a mesma regra da seleção múltipla do painel.

Opções de `submit`: `--kind output\|decision\|batch` (obrigatório), `--title <text>` (obrigatório), `--summary <text>`, `--risk none\|low\|medium\|high` (padrão `none`), `--detail <json>` (um objeto JSON), `--agent <name>` e `--session <id>` (ignorado quando não for a sessão deste projeto).

Leituras exigem `project.review.read`, vereditos exigem `project.review.act` e `submit` exige `project.review.submit`.

<a id="secrets"></a>

### Segredos

Valores criptografados armazenados no projeto. Por padrão, um segredo é injetado como uma variável de ambiente simples em cada sandbox de sessão na inicialização (exposição pelo ambiente). A entrega forçada — em que o sandbox mantém um identificador e o Beeuni substitui o valor real fora dele (exposição forçada na saída e `beeuni secrets call`) — é experimental. Ative a flag de recurso `secrets_egress` (Settings → Feature flags) para usá-la; com a flag desativada, `beeuni secrets delivery … egress` retorna `403` `feature_disabled`. Consulte [Secrets](/docs/pt/project/secrets).

| Comando | Efeito |
| --- | --- |
| `beeuni secrets ls` | Lista os segredos por identificador e especificação de manifesto `env`, indicando quem pode usar cada valor. Marca os valores obrigatórios ausentes. |
| `beeuni secrets set NAME=VALUE ... [--identifier <id>] [--scope runtime\|connector] [--only-me]` | Cria ou atualiza um ou mais segredos. `NAME=-` lê o valor da entrada padrão. `--scope connector` mantém o valor no servidor para o gateway do conector. `--only-me` torna o novo valor utilizável apenas por você. |
| `beeuni secrets share IDENTIFIER --user <email\|id\|me> --group <id> --agent <name> \| --everyone` | Define quem pode usar o valor. As pessoas o acessam diretamente ou em suas próprias sessões privadas; um agente, em todas as suas sessões, incluindo gatilhos. Consulte [Who can use a secret](/docs/pt/project/secrets#who-can-use-a-secret). |
| `beeuni secrets request NAME ... [--scope runtime\|connector] [--expires <min>]` | Cria um link para que uma pessoa insira um valor que você não possui. |
| `beeuni secrets unset NAME ...` | Remove segredos. |
| `beeuni secrets grant IDENTIFIER --agent <name>` | Permite que um agente receba este segredo: mescla o identificador na lista `secrets` desse agente em `beeuni.yaml`, adicionando a entrada do agente quando o manifesto não a incluir. |

`grant` corrige uma linha que `ls` relata como não entregável. Ele apenas amplia a lista de um agente; para restringi-la ou substituí-la, reescreva todo o conjunto com `beeuni
agents scope`. There is no `secrets revoke` — a API não tem uma rota que remova um único identificador de uma concessão. A primeira concessão em um projeto sem agentes inicia a governança: a partir daí, um agente que não esteja listado no manifesto não recebe segredos do projeto, e o comando informa isso quando ocorre.

<a id="env"></a>

### Ambiente

| Comando | Efeito |
| --- | --- |
| `beeuni env pull [--out <path>] [--force]` | Escreve um esqueleto `.env` — somente nomes. Os valores nunca saem da nuvem. |
| `beeuni env push --from <path>` | Envia cada `NAME=VALUE` de um arquivo dotenv como um segredo. |

<a id="agents"></a>

### Agentes

Configurações de modelo por agente no projeto vinculado.

| Comando | Efeito |
| --- | --- |
| `beeuni agents ls [--json]` | Mostra o modelo fixado de cada agente e o padrão alternativo. Alias: `models`. |
| `beeuni agents model <agent> <provider/model>` | Fixa um agente em um modelo. |
| `beeuni agents model <agent> --clear` | Remove a fixação — o agente volta a seguir o padrão. |
| `beeuni agents default <agent>` | Define este como o agente padrão do projeto. |
| `beeuni agents default --show [--json]` | Exibe o agente padrão atual. |
| `beeuni agents scope <agent> [--secrets all\|none\|A,B] [--connectors all\|none\|a,b] [--apps all\|none\|a,b] [--require-connector <slug>]` | Substitui os segredos, conectores e Beeuni Apps que o agente pode usar. `--apps` aceita slugs de Apps e requer um `beeuni.yaml` v2; o agente também requer `project.app.read`. `--require-connector` pode ser repetido e precisa ser resolvido antes do início de uma sessão. |
| `beeuni agents scope <agent> --show [--json]` | Exibe o escopo atual do agente. |
| `beeuni agents config <agent> [--json]` | Exibe o bloco completo de configuração do agente. |
| `beeuni agents config <agent> --file <path>` | Substitui o bloco pelo conteúdo de um arquivo JSON. `-` lê a entrada padrão. |
| `beeuni agents config <agent> --set <key>=<value> ...` | Altera chaves pontuadas individuais, mesclando-as. Pode ser repetido, por exemplo, `behavior.model=glm-5.3-flash`, `enabled=false`, `connectors=["slack"]`. |

Cada opção de escopo substitui; nenhuma faz mesclagem. Um valor `--set` é analisado como JSON quando possível e mantido como string caso contrário. As fixações de modelo e `scope` têm efeito imediato, sem commit de `beeuni.yaml`; `default` e `config` fazem commit em `beeuni.yaml` na branch padrão do projeto. `scope` requer `project.agent.write`, assim como `default` e `config`.

<a id="tools"></a>

### Ferramentas

As ferramentas que as sessões deste projeto recebem, lidas do `beeuni.yaml` local e de suas [imports](/docs/pt/project/manifest#imports). Execute a partir da raiz do projeto. Consulte [Tools](/docs/pt/project/tools).

| Comando | Efeito |
| --- | --- |
| `beeuni tools ls [--json]` | Lista cada ferramenta recebida pelas sessões: nome, tipo (`beeuni`, `beeuni (overridden)`, `project`) e origem (`beeuni:<name>` ou o caminho do módulo). Também lista as ferramentas Beeuni removidas pelo projeto. `--json` exibe `{ manifest, tools_key, tools, removed }`. |
| `beeuni tools eject <name> [--force]` | Copia a ferramenta Beeuni `<name>` para `tools/<name>.ts` e define `tools.<name>: tools/<name>.ts` em `beeuni.yaml`, no arquivo que a declara. A linha alterada termina com `# ejected from beeuni:<name>`; todos os outros comentários permanecem. Sem a chave `tools:`, também lista as outras quatro ferramentas Beeuni, portanto a ejeção não remove nada. Recusa quando `tools/<name>.ts` existe ou quando a ferramenta já aponta para outro módulo, a menos que `--force`. Recusa um nome que não seja de uma ferramenta Beeuni. |

Sem a chave `tools:`, toda sessão recebe as cinco ferramentas Beeuni (`web_search`, `image_search`, `scrape_webpage`, `memory`, `show`). Com uma chave `tools:`, as sessões recebem somente as ferramentas Beeuni listadas nela. Para remover uma ferramenta Beeuni, exclua sua linha em `tools:` e execute `beeuni validate`. Para limitar as ferramentas de um agente, use `agents.<name>.tools`. Códigos de saída: `0` concluído, `1` recusado (um arquivo existe, um manifesto ou importação não pode ser analisado), `2` sem manifesto, opção desconhecida ou nome que não seja de uma ferramenta Beeuni.

<a id="models"></a>

### Modelos

Quais modelos o projeto oferece e com qual ele começa. Mesma interface de Customize → Models no painel. Um projeto armazena somente suas exceções ao padrão do catálogo (o modelo mais recente de cada família). A ativação é apenas visual: define o que os seletores oferecem, nunca o que o gateway disponibiliza.

| Comando | Efeito |
| --- | --- |
| `beeuni models ls [--json]` | Lista todos os modelos que você pode executar: estado, origem, forma de pagamento (`VIA`: Beeuni, chave de API ou ChatGPT — seus, compartilhados com você ou compartilhados com o projeto) e provedor. |
| `beeuni models enable <model-id>...` | Oferece esses modelos. |
| `beeuni models disable <model-id>...` | Para de oferecê-los. O padrão do projeto recusa com `409` — altere primeiro o padrão. |
| `beeuni models reset` | Remove todas as exceções; volta ao padrão do catálogo. |
| `beeuni models default [--json]` | Exibe a cadeia de padrões (projeto → conta → plataforma) e para o que ela é resolvida. |
| `beeuni models default <model-id> [--account]` | Define o padrão do projeto ou, com `--account`, o padrão para toda a conta. |
| `beeuni models default --clear [--account]` | Limpa o padrão do projeto ou da conta. |

Os IDs de modelo são IDs de transmissão do gateway — um ID gerenciado simples (`glm-5.3-flash`) ou um `provider/model` BYOK. Copie um de `beeuni models ls --json`. As fixações por agente ficam em `beeuni agents model <agent> <model-id>`. As gravações requerem `project.model.write`.

<a id="channels"></a>

### Canais

Gerencia a conexão do projeto com uma plataforma de chat. Os tokens são armazenados criptografados nos segredos do projeto e resolvidos no servidor — nunca são injetados no sandbox.

| Comando | Efeito |
| --- | --- |
| `beeuni channels status [--json]` | Mostra a conexão atual. |
| `beeuni channels connect [--wait] [--timeout <sec>]` | Conecta em uma etapa: exibe um link de instalação. `--wait` consulta até a instalação ser concluída. |
| `beeuni channels connect --manual [--bot-token <token>] [--signing-secret <secret>]` | Modo de uso do próprio app: salva diretamente um token de bot e um segredo de assinatura. |
| `beeuni channels disconnect [--platform slack\|teams]` | Remove a conexão do projeto — a do Slack ou, com `--platform teams`, a do Teams. |
| `beeuni channels manifest` | Exibe o JSON do manifesto do app para o caminho de uso do próprio app. |
| `beeuni channels email status [--json]` | Caixa de entrada e modo de entrega para um conector de e-mail. |
| `beeuni channels email connect [options]` | Cria uma caixa de entrada gerenciada ou conecta uma existente do AgentMail. |
| `beeuni channels email disconnect` | Remove a conexão da caixa de entrada. |
| `beeuni channels email policy [--allow <email\|@domain>] [--allow-regex <re>] [--allow-all]` | Substitui quem pode enviar e-mails para o agente. |
| `beeuni channels bindings [ls] [--json]` | Lista todos os canais vinculados e o agente, modelo e política de entrada que eles resolvem. |
| `beeuni channels bind <bindingId> [--agent <name>\|--no-agent] [--model <id>\|--no-model] [--policy <p>]` | Altera um vínculo. `--policy` aceita `owner_approval`, `owner_only` ou `project_open`. |

`--platform slack|teams` seleciona a plataforma; padrão `slack`. Teams
`connect` imprime a URL de consentimento administrativo da Microsoft; conceder consentimento para todo o tenant
publica o app automaticamente no catálogo do Teams. Consulte [Connectors](/docs/pt/connect/connectors).

O canal de e-mail é baseado no AgentMail e precisa da flag de recurso `agentmail_email`. `email connect` opções: `--connector <slug>` (padrão `beeuni_email`),
`--api-key <k>` (use sua própria chave do AgentMail; `-` lê do stdin),
`--display-name <n>` (nome do remetente nos e-mails enviados; por padrão, o nome do projeto),
`--username <u>` e `--domain <d>` (uma nova caixa de entrada gerenciada), e
`--inbox-id <id>` com `--email <addr>` (anexa uma caixa de entrada existente — ambas são
obrigatórias em conjunto). `--allow` pode ser repetido e coloca a política no modo restrito; um valor simples sem `@`, ou um com `@` no início, é lido como um domínio.
`--allow-all` limpa a lista e aceita todos os remetentes novamente.

As gravações de e-mail e `bind` precisam de `project.connector.write`.

### Connectors

Connectors que um agente chama como ferramentas. `add`, `rm` e `policy set` editam o `beeuni.yaml` local; execute `beeuni ship` para aplicar, a menos que você passe `--apply` para alterar o projeto na nuvem imediatamente.

| Comando | Efeito |
| --- | --- |
| `beeuni connectors ls [--json]` | Lista os connectors e seus status. |
| `beeuni connectors show <slug> [--json]` | Mostra as ferramentas de um connector. |
| `beeuni connectors add <slug> --provider <p> [options] [--apply]` | Adiciona um connector. |
| `beeuni connectors rm <slug> [--apply]` | Remove um connector. |
| `beeuni connectors rename <slug> <name>` | Define o nome de exibição de um connector. |
| `beeuni connectors sync` | Reconcilia o catálogo a partir do `beeuni.yaml` incluído. |
| `beeuni connectors credential <slug> [value]` | Define a credencial de um connector. |
| `beeuni connectors connect <slug>` | Inicia um fluxo de conexão com um clique. |
| `beeuni connectors link <slug> [--expires <min>]` | Cria um link de conexão compartilhável para uma pessoa. |
| `beeuni connectors types [--connector <a,b>] [--out <file>]` | Grava tipos TypeScript para cada ação chamável: um arquivo `declare module '@beeuni/sdk'` que tipa os argumentos `connectors.callAction(slug, action, args)` e `output`. Connectors gerenciados não publicam um esquema de saída, então o resultado é `unknown`. Sem `--out`, imprime no stdout. |
| `beeuni connectors accounts <slug> [--default <label\|id>] [--json]` | Lista as contas como as quais suas chamadas podem ser executadas, com a identidade usada em cada conexão. `--default` fixa uma delas. |
| `beeuni connectors connections ls [--all] [--json]` | Lista conexões com rótulo, `CONNECTED AS`, proprietário, `WHO CAN USE` (`owner only`, `everyone` ou os rótulos de concessão, com `(not you)` quando você a lista apenas para gerenciá-la), status e padrão. |
| `beeuni connectors connections rename <id> <label…>` | Renomeia uma conexão. Apenas o rótulo muda; não há nova autorização. |
| `beeuni connectors connections share <id> [--group <id>]… [--user <email\|id>]… [--everyone]` | Compartilha sua própria conta privada: ela se torna uma conta compartilhada que somente essa pessoa pode usar (`--everyone`: o projeto inteiro). Requer o direito de gerenciar as conexões do projeto. |
| `beeuni connectors apps [<query>] [--category <c>] [--cursor <c>] [--limit <n>] [--json]` | Pesquisa o catálogo de ferramentas gerenciadas — os slugs aceitos por `add --provider composio --app <slug>`. Alias: `beeuni connectors toolkits`. Adicione `--pipedream` para o catálogo legado. |
| `beeuni connectors catalog [<query>] [--cursor <c>] [--json]` | Navega pelo catálogo de connectors diretos. Precisa da flag `connectors_api_discover`. |
| `beeuni connectors catalog show <id> [--json]` | Mostra as superfícies de um registro do catálogo. |
| `beeuni connectors sensitive <slug> on\|off` | Também controla as leituras deste connector — toda chamada passa a exigir aprovação. Aplica-se agora. |
| `beeuni connectors owner <slug> project\|user` | Define quem autoriza: uma conexão do projeto ou a própria conexão de cada membro. Aplica-se agora. |
| `beeuni connectors authorize <slug> [--status] [--scope "<a b>"] [--client-id <id>] [--client-secret <s>] [--success-redirect <url>] [--error-redirect <url>] [--json]` | Configura o OAuth 2.1 de ponta a ponta para um connector: descobre os metadados de autorização do servidor, registra o Beeuni como cliente (RFC 7591) quando o servidor oferece suporte e imprime a URL para aprovação. `--status` informa o resultado em vez disso. |
| `beeuni connectors authorize <slug> --device` | O mesmo, usando o fluxo de dispositivo OAuth 2.0 (RFC 8628): imprime um código e uma URL e consulta até que seja aprovado, negado ou expire. |
| `beeuni connectors policy ls [--json]` | Mostra a política de execução em todo o projeto. Alias: `show`. |
| `beeuni connectors policy set --default <risk\|allow_all> [--apply]` | Define o modo de execução padrão em `beeuni.yaml`. `--apply` o define imediatamente. |
| `beeuni connectors policy add <match> <allow\|ask\|block> [--condition <k=v>]` | Adiciona uma regra para todo o projeto. Aplica-se agora. `--condition` a restringe a um argumento correspondente e pode ser repetido; `k!=v` a nega, e `k` é um caminho pontilhado para os argumentos da chamada. |
| `beeuni connectors policy rm <match>` | Remove uma regra para todo o projeto. Aplica-se agora. |
| `beeuni connectors policy <slug> ls\|set <match> <allow\|ask\|block>\|rm <match>\|clear` | Gerencia as regras de chamadas de ferramentas de um connector. |

`policy ls`, `show`, `set`, `add` e `rm` são a superfície de todo o projeto; portanto, um connector nomeado com um desses verbos deve ser referenciado como `policy <slug> ls`. Um `<match>` é um nome de ferramenta, um glob (`send_*`) ou um `/regex/`.

Opções de `add`: `--name <label>`, `--provider <pipedream\|mcp\|openapi\|postman\|graphql\|http>`, `--app <slug>`, `--url <url>`, `--transport <http\|sse>`, `--endpoint <url>`, `--base-url <url>`, `--spec <url\|path>`, `--auth-type <none\|bearer\|basic\|custom>`, `--credential shared`.

### Sandboxes

Gerencia as imagens de sandbox do projeto. Um template define uma imagem ou um Dockerfile, além dos recursos; um build produz o snapshot a partir do qual as sessões são inicializadas.

| Comando | Efeito |
| --- | --- |
| `beeuni sandboxes ls [--json]` | Lista os templates e o estado atual do provedor. |
| `beeuni sandboxes builds [--json]` | Log do build mais recente. |
| `beeuni sandboxes health [--json]` | Prontidão do template principal. |
| `beeuni sandboxes add <slug> (--image <i>\|--dockerfile <p>) [options]` | Cria um template personalizado e inicia um build. |
| `beeuni sandboxes update <slug> [options]` | Atualiza um template. |
| `beeuni sandboxes build <slug>` | Inicia um novo build. |
| `beeuni sandboxes rebuild <slug>` | Força um novo build: exclui primeiro o snapshot existente. |
| `beeuni sandboxes rm <slug>` | Exclui um template. |
| `beeuni sandboxes fix` | Inicia uma sessão usando como base o log do build que falhou por último, para corrigi-lo. |
| `beeuni sandboxes provider [--json]` | Mostra a fixação do provedor de sandbox do projeto e quais provedores este host oferece. |
| `beeuni sandboxes provider <name> [--timeout <sec>]` | Fixa toda nova sessão em um provedor. Quando o destino precisa ter seu snapshot criado primeiro, a API responde com uma preparação e o comando a acompanha até a conclusão. Padrão `--timeout`: 600s. |
| `beeuni sandboxes provider --clear` | Remove a fixação e segue o padrão da plataforma. Alias: `--unpin`. |
| `beeuni sandboxes provider status [--json]` | Mostra a transição mais recente do provedor e seu histórico. Alias: `transition`. |

Fixar um provedor requer `project.settings.write`.

Opções de `add`/`update`: `--name <label>`, `--cpu <n>`, `--memory <n>` (GiB), `--disk <n>` (GiB).

### Backends

Bancos de dados são Apps com volumes persistentes. Gerencie e conecte-os por Apps.

[Apps](/docs/feature-flags/apps)

### Marketplace

Navegue pelo marketplace do Beeuni e instale um item em um projeto.

| Comando | Efeito |
| --- | --- |
| `beeuni marketplace search [query]` | Pesquisa itens do marketplace. |
| `beeuni marketplace list` | Lista itens do marketplace. |
| `beeuni marketplace show <id-or-name>` | Exibe um item do marketplace. |
| `beeuni marketplace install <id-or-name>` | Inicia uma sessão de agente que importa o item. |

Opções: `--query <text>`, `--type <type>`, `--source <source>`, `--host <name>`, `--project <id>`, `--json`.

A instalação é conduzida por um agente: ela inicia uma sessão de projeto que clona o item,
lê seu conteúdo, incorpora o que for adequado e abre uma solicitação de alteração. Não há
mecanismo determinístico para instalar, atualizar ou remover.

<a id="system-skills"></a>

### Skills do sistema

As skills do sistema Beeuni são a referência operacional da plataforma para pessoas e agentes. Elas abrangem sessões, sandboxes, runtime padrão, conectores, memória e canais. Esta página pública é o ponto de entrada; a CLI autenticada lê as skills do host em execução. Use `beeuni system-skills list` para descobrir as skills disponíveis e, em seguida, `get` para obter a que você precisa. A API as disponibiliza ao vivo, portanto elas correspondem à versão implantada do host. Não considere uma cópia local atualizada.

| Comando | Efeito |
| --- | --- |
| `beeuni system-skills list` | Lista as skills do sistema Beeuni. Subcomando padrão. |
| `beeuni system-skills get <name> [--full]` | Exibe o `SKILL.md` atual de uma skill. `--full` inclui os arquivos referenciados por ela. |
| `beeuni system-skills path [name]` | Exibe o diretório de uma skill no disco deste projeto. |

Opções: `--host <name>`, `--json`.

`beeuni skills` é um alias permanente para o mesmo comando. Primeiro, autentique-se no host com `beeuni login`; a API de skills requer autenticação. Use `--host <name>` ao trabalhar com outro host. Uma página pública de documentação não substitui estas instruções atualizadas e específicas do host.

Esta lista contém sempre as skills do sistema, nunca uma combinação de skills. As skills opcionais estão no marketplace: `beeuni marketplace list --type skill`. Para a sintaxe dos comandos, use `beeuni <command> --help`; para a referência completa da plataforma, leia `beeuni system-skills get beeuni-system --full`.

### Connector

A interface do agente no sandbox para todos os conectores. Cada chamada é verificada, resolvida e auditada no servidor; a CLI nunca armazena credenciais de terceiros. Autenticação: `BEEUNI_TOKEN`. A saída é JSON.

| Comando | Efeito |
| --- | --- |
| `beeuni connectors discover "<intent>"` | Pesquisa ferramentas por intenção em linguagem natural. |
| `beeuni connectors show <connector>.<action>` | Exibe o esquema de entrada de uma ação. |
| `beeuni connectors call <connector>.<action> '<json-args>'` | Executa uma ferramenta. Uma chamada sujeita à governança retorna imediatamente seu `approval_url` autenticado. O servidor retoma a sessão após uma decisão de aprovação ou recusa. Passe argumentos grandes como `@file.json` ou `-` (stdin). |
| `beeuni connectors call <connector>.<action> '<json-args>' --reason "<text>"` | Descreve o que a chamada faz para a pessoa que aprova quando uma política a retém. O cartão de aprovação mostra a descrição do agente ao lado dos argumentos. |
| `beeuni connectors call <connector>.<action> @args.json --attach <file>` | Prepara um arquivo e adiciona sua referência ao array de anexos da ação. O gateway grava os bytes no item de anexo do provedor. `--attach` pode ser repetido; `--attach-path <a.b.c>` indica o nome do array. Consulte [Anexar arquivos](/docs/pt/connect/connectors#attach-files). |
| `beeuni connectors call <connector>.<action> '<json-args>' --out <file>` | Grava o resultado JSON completo em `<file>` e exibe apenas um resumo: `saved_to`, `bytes` e `shape` (chaves, tamanhos de arrays, `pageInfo`). Consulte [Resultados grandes](/docs/pt/connect/connectors#large-results). |
| `beeuni connectors upload <file> --connector <slug>` | Prepara um arquivo. Exibe `ref`, `{"$beeuni_attachment":"<id>"}`, para incluir nos argumentos da chamada. |
| `beeuni connectors add <slug> --provider pipedream --app <app>` | Adiciona um conector imediatamente e, em seguida, conecta-o. |
| `beeuni connectors rm <slug>` | Remove um conector do projeto. |
| `beeuni connectors connect <slug> [--owner me\|project] [--label <name>]` | Gera um link de conexão para uma pessoa. `--label` sugere um nome para uma nova conta, por exemplo, uma segunda conta do Gmail. |

<a id="files"></a>

### Arquivos

Visualização somente leitura do repositório Git do projeto. Opera no branch padrão, a menos que `--ref` especifique outro branch, tag ou commit.

| Comando | Efeito |
| --- | --- |
| `beeuni files ls [<path>]` | Lista arquivos em um caminho, recursivamente. A lista para em 1.000 arquivos e informa isso; restrinja-a com um caminho ou use `files search`. |
| `beeuni files cat <path>` | Exibe o conteúdo de um arquivo. |
| `beeuni files search <query> [--content]` | Pesquisa nomes de arquivos ou o conteúdo dos arquivos com `--content`. |
| `beeuni files history <path>` | Histórico de commits de um arquivo. |
| `beeuni files branches` | Lista branches. |
| `beeuni files commits [--path <p>]` | Lista commits em `--ref`. |
| `beeuni files show <sha>` | Exibe um commit e os arquivos alterados. |
| `beeuni files diff <sha> [--path <p>]` | Exibe o patch unificado de um commit. |
| `beeuni files compare <from> <into>` | Resume o diff entre duas refs. |
| `beeuni files download -o <out.zip>` | Baixa o repositório ou a subárvore `--path` em `--ref` como um arquivo zip. Alias: `archive`. |

Opções em todos os subcomandos: `--ref <ref>`, `--path <p>`, `--limit <n>`, `--json`.
`download` também aceita `-o, --out <file>`, que é obrigatório.

Todos os subcomandos precisam de `project.file.read`. `download` também recusa qualquer
subárvore que inclua um agente ou skill fora do seu escopo — não é possível filtrar um arquivo zip durante a transmissão —, então, nesse caso, arquive um `--path` mais restrito.

<a id="triggers"></a>

### Gatilhos

Um gatilho inicia uma sessão a partir de uma programação, um webhook, um evento de app ou um monitor (experimental). `add`, `rm`, `enable`, `disable` editam o manifesto local — execute `beeuni ship` para aplicar. `pause`/`resume` alternam uma chave separada, no servidor. Consulte [Gatilhos](/docs/pt/connect/triggers).

| Comando | Efeito |
| --- | --- |
| `beeuni triggers ls [--json]` | Lista os gatilhos e o estado de execução. |
| `beeuni triggers add <slug> [options] [--apply]` | Adiciona um gatilho ao manifesto. `--apply` o cria agora no projeto na nuvem: faz commit em `beeuni.yaml` em `main` e reconcilia. |
| `beeuni triggers set <slug> [options]` | Altera um gatilho ativo. Apenas os sinalizadores informados são gravados. Sempre aplica a alteração agora — não há versão local. Alias: `update`. |
| `beeuni triggers rm <slug> [--apply]` | Remove um gatilho de `beeuni.yaml` ou do projeto na nuvem agora com `--apply`. |
| `beeuni triggers info <slug> [--json]` | Exibe um gatilho. |
| `beeuni triggers events --connector <slug> [--json]` | Lista os eventos oferecidos por um conector, com as configurações de cada evento. |
| `beeuni triggers fire <slug>` | Dispara um gatilho manualmente e aguarda o resultado da execução: uma execução com falha retorna um código diferente de zero e o erro, e a sessão nova do disparo é limpa (uma execução enfileirada em uma sessão existente permanece). `--wait <dur>` limita o tempo de espera (padrão `90s`; `0` retorna assim que o disparo é aceito). |
| `beeuni triggers enable <slug> [--apply]` / `disable <slug> [--apply]` | Ativa ou desativa um gatilho. |
| `beeuni triggers pause` / `resume` | Desativa ou reativa todos os gatilhos do projeto, no servidor. |

Opções de `add`: `--type <cron\|webhook\|event\|monitor>` (padrão `cron`), `--prompt <text>` (obrigatório), `--agent <name>`, `--cron <expr>` (6 campos, por exemplo `"0 0 9 * * 1-5"`), `--run-at <iso>` (executa uma vez neste instante, em vez de usar um cron), `--timezone <tz>` (padrão UTC), `--secret-env <NAME>`, `--name <label>`, `--disabled`.

Opções exclusivas para gatilhos ativos — válidas em `add --apply` e em todo `set`: `--model <provider/model>`, `--session-mode <fresh\|keyed\|pinned\|reuse>`, `--session-key <tmpl>` (agrupa uma sessão por chave, por exemplo `"{{ body.data.chat_jid }}"`; implica `keyed`), `--session-id <id>` (a sessão em que um gatilho `pinned` faz o loop; precisa ser uma sessão deste projeto), `--session-access <private\|project\|members>` (padrão `private`), `--member <uuid>` e `--group <uuid>` (repetíveis; cada um implica `members`), e `--filter <path=value>` (repetível; todos precisam corresponder, por exemplo `--filter body.type=push`).

`set` aceita todas as opções exclusivas para gatilhos ativos, além de `--name`, `--prompt`, `--cron`, `--run-at`, `--timezone`, `--secret-env`, `--agent` e `--enabled true|false`. `--cron` e `--run-at` são mutuamente exclusivos: definir um limpa o outro. Os campos de monitor são apenas aditivos.

<a id="reminders"></a>

### Lembretes

Um lembrete envia um novo prompt a uma sessão mais tarde, uma vez ou repetidamente. Ele é armazenado no banco de dados, não em `beeuni.yaml`. Dentro de uma sessão, `--session` usa `$BEEUNI_SESSION_ID` como padrão. Consulte [Lembretes](/docs/pt/connect/reminders).

| Comando | Efeito |
| --- | --- |
| `beeuni remind "<text>" [schedule]` | Cria um lembrete. Equivale a `beeuni reminders add`. |
| `beeuni reminders add "<text>" [schedule]` | Cria um lembrete. Exibe o ID e o próximo disparo. |
| `beeuni reminders ls [--json]` | Lista os lembretes da sessão. |
| `beeuni reminders pause <id>` / `resume <id>` | Desativa ou ativa um lembrete. `resume` o reativa a partir de agora. |
| `beeuni reminders rm <id>` | Exclui um lembrete. Aliases: `stop`, `delete`. |

Opções de programação: `--in <duration>` ou `--at <iso>` (primeiro disparo; se usado sozinho, dispara uma vez), `--every <duration>` (repetição, mínimo de `5m`), `--cron "<expr>"` com `--timezone <tz>`. Outras opções: `--name <label>`, `--session <id>` (um prefixo único funciona), `--project <id>`, `--host <name>`, `--json`.

Opções de evento (`--type event`): `--connector <slug>` e `--event <TYPE>` (ambas obrigatórias), `--config key=value` (repetível, valores de texto) e `--config-json '{...}'` (valores tipados). `set` aceita os mesmos sinalizadores. Um gatilho de evento rejeita `--cron`, `--run-at`, `--timezone`, `--secret-env` e as opções de monitor. O prompt lê `{{ event.data.<field> }}`; consulte [Gatilhos de eventos de app](/docs/pt/connect/triggers#app-event-triggers).

Opções de monitor (`--type monitor`): `--run <cmd>` (comando relativo ao repositório para monitorar; obrigatório), `--mode <poll\|stream>` (obrigatório; `poll` executa novamente em `--interval`, `stream` mantém o comando em execução), `--interval <dur>` (somente `mode=poll`, mínimo de 30 s, por exemplo `60s`, `5m`) e `--expect-event-within <dur>` (monitor de inatividade; se nenhum evento ocorrer dentro do intervalo, dispara um evento de ciclo de vida em vez disso; mínimo de 5 min, por exemplo `24h`). Um monitor é um comando do repositório que a plataforma executa 24 horas por dia, 7 dias por semana; cada linha de stdout dispara o gatilho. É experimental: a plataforma executa monitores apenas onde o sinalizador de recurso `monitors` está ativado.

<a id="access"></a>

### Acesso

A interface CLI da tabela única de concessões. Cada linha é uma **atribuição**: um
principal, uma função, um escopo, opcionalmente restringida a um objeto. Consulte
[Contas e acesso](/docs/pt/accounts#one-access-model) para entender o modelo. Funções da conta:
`owner`, `admin`, `member`. Funções do projeto: `manager`, `member`.

| Comando | Efeito |
| --- | --- |
| `beeuni access assignments [--project <id>\|--account\|--all] [--json]` | Lista as atribuições em um projeto, na conta ou em todos os lugares. |
| `beeuni access grant --user <id\|email>\|--group <id>\|--service-account <id> --role <key\|id> [opts]` | Cria uma atribuição. Exibe o ID da atribuição. |
| `beeuni access revoke <assignment-id>` | Revoga uma atribuição. |

Opções de concessão: `--project <id>` (padrão: o projeto vinculado), `--account` (a conta inteira), `--agent <name>` (restringe a concessão a um agente — uma atribuição de objeto), `--connection <id>` (restringe o uso de uma conta de conector compartilhada; a primeira concessão limita a conta aos seus beneficiários, e revogar a última a libera novamente para todo o projeto), `--everyone` (concede acesso a todos que têm acesso ao projeto; contém um `--agent` ou um `--connection`, nunca uma função) e `--expires <iso>` (data e hora de revogação automática). `--principal` filtra uma lista e aceita `user:<id>`, `group:<id>`, `service_account:<id>`, `project:<id>` ou `pending:<email>`; um ID sem prefixo é interpretado como usuário. Uma concessão a todos aparece na lista como `everyone`. A identidade de um agente é um `service_account`, então `--service-account <id>` é a forma de atribuir uma função a um agente. `--user` aceita um e-mail e o resolve no diretório de membros da conta.

```bash
beeuni access grant --user alice@corp.com --role manager
beeuni access grant --user alice@corp.com --role admin --account
beeuni access grant --group 8f3c… --role member --project 1a2b…
beeuni access grant --user alice@corp.com --agent support-bot
beeuni access grant --everyone --agent support-bot
beeuni access grant --group 8f3c… --connection 2b7e…
beeuni access revoke 4d5e…
```

Os verbos de membro do projeto são uma visualização de leitura das mesmas atribuições:

| Comando | Efeito |
| --- | --- |
| `beeuni access ls [--json]` | Lista as pessoas com acesso ao projeto, a função na conta e a função efetiva no projeto. |
| `beeuni access invite <email> --role <r>` | Convida alguém para o projeto. Cria uma atribuição `pending`. |
| `beeuni access grant <user-id> --role <r>` | Define a função de um usuário no projeto. |
| `beeuni access revoke <user-id>` | Remove o acesso de um usuário ao projeto. |
| `beeuni access pending [--json]` | Lista os convites pendentes. |
| `beeuni access resend <invite-id>` | Reenvia o e-mail de convite e renova o prazo de validade de 14 dias. Também exibe o link. |
| `beeuni access cancel <invite-id>` | Cancela um convite pendente. |
| `beeuni access requests ls [--json]` | Lista as solicitações pendentes de pessoas que querem participar deste projeto. |
| `beeuni access requests approve <req-id> [--role <r>]` | Aprova uma solicitação e concede a função no projeto. Função padrão: `member`. |
| `beeuni access requests reject <req-id>` | Rejeita uma solicitação. Alias: `deny`. |

Todos os verbos nos dois blocos acima precisam de `project.members.manage`.

Uma pessoa, um grupo ou um agente recebe funções do Beeuni; além disso, um agente
carrega permissões do Beeuni em `beeuni.yaml`, e uma sessão só pode fazer o que ambos
permitem. Consulte [Um vocabulário, duas associações](/docs/pt/accounts#one-vocabulary-two-bindings).

<a id="audit"></a>

### Auditoria

Os comandos de auditoria leem o log centralizado de reconstrução. As listas de contas e projetos são ordenadas da mais recente para a mais antiga. A linha do tempo de uma sessão é ordenada pelo horário de criação
(`session_sequence` só é definido em linhas gravadas antes de 2026-10; elas aparecem
primeiro). `--all` acompanha cada cursor de continuação. `ls` lista os últimos 90 dias; `export` retrocede 365 dias, e os eventos com mais de 90 dias vêm do arquivo (consulte [Retenção da auditoria](/docs/pt/accounts#retention)). A tabela mostra o título de cada linha (`EVENT`, por exemplo, "Chave do gateway LLM revogada") ao lado de seu
`ACTION` (`gateway.key.revoke`); `--action` filtra pelo prefixo da ação. Todas as
ações e títulos: [Ações do log de auditoria](/docs/pt/audit-actions).

| Comando | Efeito |
| --- | --- |
| `beeuni audit ls [filters] [--all] [--json]` | Lista os eventos da conta. |
| `beeuni audit project <project-id> [filters] [--all] [--json]` | Lista os eventos de um projeto. |
| `beeuni audit session <session-id> --project <project-id> [--all] [--json]` | Reconstrói uma sessão em ordem. |
| `beeuni audit export [filters] --format csv\|jsonl --out <file>` | Continua cada página da exportação e reúne tudo em um arquivo. |
| `beeuni audit webhooks ls [--json]` | Lista os webhooks de auditoria da conta. |
| `beeuni audit webhooks add --name <n> --url <u> [--action-prefix <p>]` | Cria um. O segredo de assinatura é exibido uma única vez, e um envio de teste ocorre imediatamente. `--action-prefix` envia apenas ações com esse prefixo. |
| `beeuni audit webhooks enable <webhook-id>` | Retoma o envio. |
| `beeuni audit webhooks disable <webhook-id>` | Pausa o envio, mantendo o endpoint. |
| `beeuni audit webhooks rm <webhook-id>` | Exclui permanentemente um webhook. |

Os webhooks de auditoria transmitem o histórico para um SIEM. Todos os verbos precisam de `account.write`;
`add` e `enable` também precisam do direito de acesso empresarial. `disable` e `rm`
nunca precisam.

Filtros: `--actor`, `--actor-type`, `--project`, `--session`, `--source`,
`--phase`, `--outcome`, `--action`, `--resource-type`, `--request-id`,
`--correlation-id`, `--query`, `--since`, `--until`, `--cursor` e `--limit`.
As listas e exportações da conta exigem `audit.read` e o direito de acesso `auditAccess` da conta.
As listas de todo o projeto exigem `project.members.manage`, pois podem incluir metadados de sessões privadas. A reconstrução de sessões exige
`project.session.read` e visibilidade dessa sessão.

<a id="roles"></a>

### Funções

Uma função é um conjunto nomeado de permissões. As funções do sistema (`owner`, `admin`, `member`
no escopo da conta; `manager`, `member` no escopo do projeto; além de `agent-user`, o
marcador carregado por uma atribuição a um objeto) são referências somente leitura. Você pode criar e editar funções personalizadas; isso requer o direito de acesso empresarial `rbac`.

| Comando | Efeito |
| --- | --- |
| `beeuni roles ls [--json]` | Lista as funções do sistema e personalizadas. |
| `beeuni roles show <role> [--json]` | Exibe as permissões e o uso de uma função. |
| `beeuni roles permissions <role> [--json]` | Lista as permissões de uma função. |
| `beeuni roles create <key> --name <n> [options]` | Cria uma função personalizada. |
| `beeuni roles edit <role> [--name <n>] [--desc <t>\|--no-desc]` | Renomeia ou altera a descrição de uma função personalizada. A chave dela nunca muda. Requer `role.update` e não permite alterar uma função do sistema. |
| `beeuni roles set-actions <role> --actions a,b` | Substitui as permissões de uma função personalizada. |
| `beeuni roles rm <role>` | Exclui uma função personalizada. |
| `beeuni roles export [--project <id>] [--out <file>] [--format toml\|json]` | Exporta funções e atribuições para um arquivo. |
| `beeuni roles import <file>` | Aplica um arquivo de funções e atribuições. |

Associe uma função a um principal com `beeuni access grant`. Os verbos mais antigos `beeuni roles
assign` / `unassign` / `assignments` ainda funcionam e gravam na mesma tabela,
mas `beeuni access` é o método documentado. `beeuni roles actions` foi substituído
por `beeuni permissions ls`.

Uma função personalizada só adiciona permissões. O Beeuni não tem regras de negação, então uma função não pode impedir que um gerente tenha uma permissão.

<a id="permissions"></a>

### Permissões

O catálogo de permissões em formato de dados. Uma linha por ação terminal, com o escopo em que ela é decidida, se pode ser delegada e o que implica. As funções são criadas a partir dessas chaves — `beeuni roles create --actions` e `beeuni roles set-actions` aceitam
exatamente essas chaves. Alias: `beeuni perms`.

| Comando | Efeito |
| --- | --- |
| `beeuni permissions ls [--scope account\|project] [--area <a>] [--json]` | Lista o catálogo. |
| `beeuni permissions show <action> [--json]` | Exibe todos os detalhes de uma ação. |

<a id="grants"></a>

### Concessões

Atribui um objeto do projeto a um principal — uma **atribuição a objeto**. Os segredos e conectores ficam nos agentes; portanto, atribuir um agente a uma pessoa concede tudo o que o agente declara. Por padrão, um agente é fechado: um membro só tem acesso a ele quando uma atribuição o identifica diretamente ou identifica um dos grupos aos quais pertence. `beeuni access grant --agent
<name>` grava a mesma linha.

| Comando | Efeito |
| --- | --- |
| `beeuni grants ls [--json]` | Lista as atribuições a objetos e os agentes que podem ser atribuídos. |
| `beeuni grants assign <agent-name> --to <who> [--group]` | Atribui um agente a um usuário ou a um grupo com `--group`. |
| `beeuni grants revoke <grant-id>` | Revoga uma atribuição a objeto. |

<a id="manifest-validation"></a>

### Validação do manifesto

| Comando | Efeito |
| --- | --- |
| `beeuni validate [--file <path>] [--json] [--scopes] [--no-dockerfile-lint]` | Valida o manifesto em relação ao esquema canônico, verifica todos os Dockerfiles do sandbox e a configuração dos agentes e confere o tamanho do repositório. Resolve `beeuni.yaml` primeiro e, em seguida, `beeuni.toml`. Códigos de saída: `0` válido (pode haver avisos), `1` erros, `2` arquivo ausente. `beeuni ship` executa as mesmas verificações. |
| `beeuni schema [--version 1\|2] [--url]` | Exibe o JSON Schema do manifesto. `--url` exibe o URL do esquema. |

Consulte [Referência do manifesto](/docs/pt/project/manifest).

<a id="repository-size"></a>

#### Tamanho do repositório

Uma sessão cria a [configuração do agente](/docs/pt/work/runtime#where-a-box-gets-the-release) a partir de todos os arquivos rastreados pelo Git no commit base. Uma nova sessão obtém esses arquivos do próprio checkout, qualquer que seja o tamanho. Uma sessão em execução recebe as alterações da ramificação base por meio do snapshot do projeto, que o Beeuni na nuvem cria com até 512 MiB compactados; acima disso, a sessão mantém a configuração em execução até o início de uma nova sessão. Toda sessão também baixa todos os arquivos. `beeuni validate` contabiliza os arquivos armazenados pelo Git, além dos arquivos não rastreados que `beeuni ship` adiciona no próximo commit, e exibe um aviso quando um arquivo tem 10 MiB ou mais ou quando o total ultrapassa 512 MiB. Um arquivo do Git LFS é contabilizado como seu ponteiro, pois a versão inclui apenas o ponteiro. O aviso identifica os maiores arquivos. O comando nunca falha.

Para eliminar o aviso:
- Mova arquivos estáticos grandes (vídeos, imagens, conjuntos de dados, pesos de modelos) para um armazenamento de objetos como S3, R2 ou GCS, ou para uma CDN, e baixe-os durante a execução.
- Adicione a saída da compilação (`dist/`, `out/`) a `.gitignore`.
- Para um caminho que precisa permanecer no Git, mas que nenhum agente lê, adicione `<path> export-ignore` a `.gitattributes`. A versão não o inclui, e a verificação também não; uma regra de diretório abrange tudo o que estiver dentro dele. O diretório de configuração do agente e `beeuni.yaml` são sempre incluídos por completo.

<a id="token-scope"></a>

### Escopo do token

Cada token começa com `beeuni_pat_`. Um token de usuário se aplica a todos os projetos das suas contas. Um token de projeto se aplica a um único projeto e é injetado automaticamente nos sandboxes desse projeto. Consulte a referência completa da família de tokens em [Runtime da sessão](/docs/pt/work/runtime).

<a id="exit-codes"></a>

### Códigos de saída

| Código | Significado |
| --- | --- |
| `0` | Sucesso. |
| `1` | Falha na operação. Os diagnósticos são impressos em stderr. |
| `2` | Flag inválida, subcomando desconhecido ou argumento obrigatório ausente. |