CLI

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.

Instalação

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.

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.

Ciclo de desenvolvimento

Este ciclo pressupõe que a CLI está instalada e que você executou beeuni login. Consulte Início rápido para configurar.

beeuni init my-app
cd my-app

beeuni projects link <project-id>

beeuni ship

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

beeuni connect

beeuni sessions chat

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

beeuni sessions shell

beeuni sessions ls

beeuni cr ls
beeuni cr diff 1
beeuni cr merge 1

Referência

Comandos de autenticação

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

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.

Contas

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.

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.

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>.

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).

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.

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.

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

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.

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.

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.

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.

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: beeuni.yaml mesclado com cada arquivo listado em 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.

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.

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

Sessões

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

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.

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.

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.

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.

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.

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.

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.

Ambiente

Agentes

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

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.

Ferramentas

As ferramentas que as sessões deste projeto recebem, lidas do beeuni.yaml local e de suas imports. Execute a partir da raiz do projeto. Consulte Tools.

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.

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.

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.

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.

--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.

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.

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.

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

Marketplace

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 para entender o modelo. Funções da conta: owner, admin, member. Funções do projeto: manager, member.

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.

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:

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.

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). 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.

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.

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.

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.

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.

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.

Validação do manifesto

Consulte Referência do manifesto.

Tamanho do repositório

Uma sessão cria a configuração do agente 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.

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.

Códigos de saída