---
title: "CLI"
description: "La riga di comando di beeuni, il suo modello di autenticazione, il ciclo di sviluppo e tutti i comandi."
---

L’interfaccia a riga di comando (CLI) di `beeuni` controlla Beeuni da un terminale, sul tuo laptop o in una sandbox di sessione. Questa pagina illustra il ciclo di sviluppo quotidiano, poi elenca tutti i comandi e i flag stabili.

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

## Installazione

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

Il programma di installazione scarica un binario precompilato per macOS e Linux. Windows non è supportato.

| Comando | Effetto |
| --- | --- |
| `beeuni update` | Esegue di nuovo lo script di installazione e scarica il binario più recente. |
| `beeuni uninstall [-y\|--yes] [--keep-auth] [--keep-home]` | Rimuove il binario, lo shim `/usr/local/bin` e il token memorizzato. `--keep-auth` conserva il token. `--keep-home` conserva `~/.beeuni`. |
| `beeuni version` | Stampa la versione della CLI. |

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

## Modello di autenticazione

Beeuni memorizza l’autenticazione per host, non globalmente. Un host è un endpoint API di Beeuni. Usa `cloud` per connetterti a Beeuni.

Il file di configurazione si trova in `~/.config/beeuni/config.json`, con modalità `0600`. Puoi modificarne il percorso con `BEEUNI_CONFIG_FILE`.

La CLI segue una gerarchia: host → account → progetto → sessione. Accedi a un host, scegli un account al suo interno, scegli un progetto nell’account e apri sessioni nel progetto. `beeuni hosts login` esegue in ordine i primi tre passaggi: ti fa accedere, sceglie l’account e imposta un progetto predefinito.

Ogni token inizia con `beeuni_pat_`. Un token utente, ottenuto con `beeuni login`, consente di vedere tutti gli account e i progetti di cui fai parte. Un token di progetto viene creato automaticamente per una sandbox di sessione ed è limitato a un solo progetto. Vedi [Ambito del token](#token-scope).

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

## Il ciclo di sviluppo

Questo ciclo presuppone che la CLI sia installata e che tu abbia eseguito `beeuni login`. Per la configurazione, vedi [Avvio rapido](/docs/it/quickstart).

1. **Collega un repository**

    Avvia un nuovo progetto oppure collega a un progetto una cartella di un repository esistente.

    Per creare un nuovo progetto:

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

    `beeuni init` crea una directory di progetto con lo starter generico. Il suo
    `beeuni.yaml` dichiara `beeuni_version: 2` ed esegue l’[harness](/docs/it/work/harnesses) del runtime predefinito.

    Per collegare un repository clonato esistente a un progetto già creato:

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

    Questo comando scrive `.beeuni/link.json` nella directory corrente. Beeuni legge questo file per individuare il progetto a ogni comando eseguito da questa cartella. Se intendi eseguire prima `beeuni ship`, salta questo passaggio. Se non esiste alcun progetto, il comando ne collega uno nuovo.

2. **Pubblica il tuo codice**

    ```sh
    beeuni ship
    ```

    `beeuni ship` esegue il lint di `beeuni.yaml`, crea un commit delle modifiche locali, invia il tuo branch e chiede eventuali segreti o connessioni mancanti. Eseguilo ogni volta che vuoi portare le modifiche locali nel progetto cloud. La prima esecuzione crea anche il progetto cloud e il repository, se non ne hai ancora collegato uno.

3. **Avvia e collegati alle sessioni**

    Avvia una sessione con un prompt:

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

    Ogni sessione viene eseguita nella propria sandbox e nel proprio branch. `--wait` resta in attesa finché la sessione non è pronta.

    Collegati a una sessione dal terminale:

    ```sh
    beeuni connect
    ```

    Senza un ID di sessione, `beeuni connect` (alias: `attach`) apre un selettore di sessione per il progetto associato: le sessioni in esecuzione si collegano subito, quelle interrotte vengono prima avviate e `+ New session` avvia una nuova sandbox. Poi apre l’interfaccia TUI completa del runtime predefinito collegata a quella sessione. Passa un ID per saltare il selettore:
    `beeuni connect <session-id>`.

    La CLI gestisce per te il binario `opencode`: al primo collegamento scarica la versione esatta in esecuzione sul server della sessione e la memorizza nella cache in `~/.beeuni/opencode/<version>/`, così la TUI e il server usano sempre la stessa versione. Imposta
    `BEEUNI_OPENCODE_BIN` per forzare l’uso di un tuo binario.

    Una sessione con l’[harness](/docs/it/work/harnesses) pi non ha un server del runtime predefinito.
    `beeuni connect` restituisce il codice di uscita 1 in questo caso, con il messaggio `This session's runtime does
    not support attaching a terminal client.`

    Per una chat testuale più leggera, invece della TUI completa, esegui:

    ```sh
    beeuni sessions chat
    ```

    Si apre una chat interattiva con la sessione più recente. Aggiungi un ID per selezionare una sessione specifica: `beeuni sessions chat <id>`.

    Per usare dal terminale l’intero prodotto — l’elenco delle sessioni, la trascrizione e il compositore, una shell nella sandbox e le schermate File, Revisione, App, Personalizza e Account — esegui il client terminale sperimentale:

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

    Accede usando l’host a cui sei già connesso. Vedi [la pagina della TUI](/docs/it/cli#sessions).

    Per aprire una shell diretta nella sandbox, senza agenti, esegui:

    ```sh
    beeuni sessions shell
    ```

    Puoi elencare in qualsiasi momento le sessioni in esecuzione:

    ```sh
    beeuni sessions ls
    ```

4. **Esamina con richieste di modifica**

    Un agente apre una richiesta di modifica (CR) quando la sessione ha commit pronti per l’unione. Puoi elencarle, esaminarle e unirle dalla CLI.

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

    `beeuni cr ls` elenca le richieste di modifica del progetto collegato. `beeuni cr diff <cr>` mostra la patch unificata. `beeuni cr merge <cr>` la unisce al branch predefinito del progetto. Accetta un numero di CR o il suo ID completo.

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

## Riferimento

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

### Comandi di autenticazione

| Comando | Effetto |
| --- | --- |
| `beeuni login [--host <name>] [--api <url>] [--token <pat>] [--account <slug>] [--no-project]` | Accede all’host attivo o a quello specificato. Per impostazione predefinita apre un browser; `--token` esegue l’accesso senza interfaccia grafica. `--no-project` salta la scelta del progetto predefinito. |
| `beeuni logout [--host <name>]` | Rimuove il token dell’host attivo o di quello specificato. |
| `beeuni whoami [--host <name>] [--json] [--token-only]` | Stampa l’utente connesso e l’account attivo. |
| `beeuni token [--host <name>]` | Scorciatoia per `beeuni whoami --token-only`. |

`beeuni hosts login` / `hosts logout` / `hosts whoami` sono le forme canoniche. `login` / `logout` / `whoami` sono scorciatoie che agiscono sull’host attivo.

<a id="hosts"></a>

### Host

| Comando | Effetto |
| --- | --- |
| `beeuni hosts ls [--json]` | Elenca tutti gli host e il relativo stato di autenticazione. |
| `beeuni hosts login [<name>] [--token <pat>] [--api <url>] [--account <slug>] [--no-project]` | Accede a un host. Se il nome non è noto, registra prima l’host. |
| `beeuni hosts logout [<name>]` | Rimuove il token di un host. |
| `beeuni hosts use <name>` | Cambia l’host attivo. |
| `beeuni hosts add <name> --url <url> [--dashboard-url <url>] [--login]` | Registra un nuovo host. `--login` esegue subito l’accesso. |
| `beeuni hosts rm <name> [--force]` | Rimuove un host. |
| `beeuni hosts info [<name>] [--json]` | Mostra i dettagli di un host. |
| `beeuni hosts current [--json]` | Stampa il nome dell’host attivo. |

L’URL di un host remoto che inizia con `http://` viene convertito in `https://`. La CLI non invia mai token a un host remoto tramite HTTP non cifrato. `localhost` fa eccezione.

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

### Account

| Comando | Effetto |
| --- | --- |
| `beeuni accounts ls [--json]` | Elenca gli account di cui fai parte sull’host attivo. |
| `beeuni accounts use [<slug-or-id>]` | Cambia l’account attivo. |
| `beeuni accounts current [--json]` | Stampa l’account attivo. |
| `beeuni accounts info [<slug-or-id>] [--json]` | Mostra un account. |

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

### Membri

Chi fa parte dell’account e quale ruolo ricopre nell’account. I ruoli sono `owner`,
`admin` e `member`. Proprietari e amministratori hanno implicitamente il ruolo Manager in ogni progetto, quindi `member` è l’unico ruolo a cui vengono assegnate autorizzazioni per singolo progetto.

| Comando | Effetto |
| --- | --- |
| `beeuni members ls [--json]` | Elenca i membri, i ruoli e il numero di progetti. |
| `beeuni members invite <email> --role admin\|member [--project <id>:<role>]` | Invita tramite email. Un utente Beeuni esistente viene aggiunto subito; chiunque altro riceve via email un link di invito. `--project` può essere ripetuta e viene applicata quando l’invito è accettato. Richiede `member.invite`. |
| `beeuni members set-role <user\|email> --role owner\|admin\|member` | Modifica il ruolo nell’account. Richiede `member.update`; solo il proprietario può assegnare il ruolo `owner`. |
| `beeuni members rm <user\|email> [-y\|--yes]` | Rimuove un membro e revoca i suoi token. Richiede `member.remove`. |
| `beeuni members super-admin <user\|email> on\|off` | Concede o revoca l’esenzione super-admin. Richiede `member.super_admin.grant`. |
| `beeuni members invites ls [--json]` | Elenca gli inviti in sospeso che hai inviato. |
| `beeuni members invites cancel <invite-id>` | Annulla un invito in sospeso. |
| `beeuni members invites resend <invite-id>` | Invia di nuovo l’email e aggiorna la scadenza di 14 giorni. |

Un `<user>` è un ID utente o l’email di una persona già presente nell’account.
Opzioni: `--account <id>`, `--host <name>`, `--json`, `-y`.

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

### Gruppi

Un gruppo di account è un insieme di persone a cui assegni un ruolo una sola volta. Associa un gruppo a un ambito con `beeuni access grant --group <id> --role <key>`; revoca con `beeuni access revoke <assignment-id>`.

| Comando | Effetto |
| --- | --- |
| `beeuni groups ls [--json]` | Elenca i gruppi con il numero di membri e progetti. |
| `beeuni groups create <name> [--description <t>]` | Crea un gruppo. |
| `beeuni groups set <group> [--name <n>] [--description <t>\|--no-description]` | Rinomina un gruppo o ne modifica la descrizione. |
| `beeuni groups rm <group> [-y\|--yes]` | Elimina un gruppo. Le relative autorizzazioni vengono eliminate con esso. |
| `beeuni groups members <group> [--json]` | Elenca i membri di un gruppo. |
| `beeuni groups add <group> <user>...` | Aggiunge una o più persone. |
| `beeuni groups remove <group> <user>` | Rimuove una persona. |
| `beeuni groups projects <group> [--json]` | Mostra a quali progetti ha accesso il gruppo e con quale ruolo. |

Un `<group>` è un ID di gruppo o il suo nome esatto. Per le operazioni di lettura serve `group.read`.
Per `create`, `set` e `add` serve `group.update` o `group.members.manage`, oltre all'autorizzazione enterprise `rbac`. `rm` e `remove` servono per la pulizia e non sono mai soggetti a limitazioni di autorizzazione.

<a id="tokens"></a>

### Token

Credenziali non interattive per l'account. Per le operazioni di lettura serve `token.read`. Ogni membro dell'account può creare e revocare le proprie chiavi personali (`token.personal.create`, `token.personal.revoke`); una chiave personale agisce come te e non ha mai più ruoli dei tuoi. Per gli account di servizio e le chiavi di altre persone servono `token.create` / `token.revoke` (owner e admin).

| Comando | Effetto |
| --- | --- |
| `beeuni tokens ls [--mine] [--json]` | Elenca le chiavi API personali dell'account. `--mine` limita l'elenco a quelle che hai creato. |
| `beeuni tokens new <name> [--expires <when>] [--project <id>]` | Crea una chiave. Il segreto viene mostrato una sola volta. `--project` la associa a un solo progetto, da cui non potrà mai uscire. |
| `beeuni tokens rm <token-id> [-y\|--yes]` | Revoca immediatamente una chiave. |
| `beeuni tokens apps ls [--json]` | Elenca le app collegate: le app e i client MCP che hai approvato con Sign in with Beeuni, in tutti gli account. |
| `beeuni tokens apps rm <client-id> [-y\|--yes] [--json]` | Revoca un'app collegata: i suoi token smettono subito di funzionare e l'app dovrà chiederti di nuovo l'autorizzazione. |
| `beeuni tokens service-accounts ls [--json]` | Elenca gli account di servizio. |
| `beeuni tokens service-accounts new <name> [--description <t>] [--expires <when>]` | Crea un account di servizio. Il token bearer viene mostrato una sola volta. |
| `beeuni tokens service-accounts disable <id>` | Disabilita un account di servizio: non può più autorizzare operazioni. Per ripristinarlo, eliminalo e ricrealo. |
| `beeuni tokens service-accounts rm <id> [-y\|--yes]` | Elimina definitivamente un account di servizio. |

Una chiave API personale agisce come te e smette di funzionare quando termina la tua appartenenza. Un account di servizio agisce per conto proprio e non eredita alcun accesso: un account nuovo non dispone di autorizzazioni. Concedigliene una con `beeuni access grant --service-account <id> --role <key>`.
`--expires <when>` accetta una data ISO-8601 o una durata futura: `30d`, `12h`, `6w`, `1y`.

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

### Fatturazione

Leggi il piano, i crediti e le spese dell'account attivo. Sola lettura: per modificare i piani, ricaricare il saldo e gestire i metodi di pagamento, usa la dashboard.

| Comando | Effetto |
| --- | --- |
| `beeuni billing status [--json]` | Piano, crediti, postazioni e abbonamento. |
| `beeuni billing transactions [--limit <n>] [--offset <n>] [--type <a,b>] [--json]` | Registro dei crediti, dal più recente. Numero predefinito di risultati per pagina: 50. |
| `beeuni billing transactions --summary\|--breakdown\|--usage [--days <n>]` | Crediti in entrata/uscita, ripartizione del saldo (in scadenza/senza scadenza/giornaliero) o riepilogo dell'utilizzo dei crediti. `--days` definisce l'intervallo per `--summary` e `--usage`; il valore predefinito è 30. |
| `beeuni billing costs [--since <iso>] [--until <iso>] [--json]` | Spesa dell'account in un intervallo, con ripartizione per modello. Intervallo predefinito: 30 giorni, semiaperto `[from, to)` UTC. |
| `beeuni billing costs --by project\|session [--sort <k>] [--limit <n>] [--offset <n>] [--csv <file>]` | Raggruppa le spese per progetto o sessione. `--sort` accetta `total_desc` (predefinito), `total_asc`, `recent` o `name_asc` (solo `--by project`). Per `--csv` serve `--by`. |

Filtri: `--project <id>`, `--session <id>` e `--owner <id>` (sessioni, con `--by session`). Opzioni: `--account <id>`, `--host <name>`, `--json`.

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

### Progetti

Un comando individua «il progetto» in quest'ordine:

1. Il flag `--project`.
2. La variabile d'ambiente `BEEUNI_PROJECT_ID`.
3. `.beeuni/link.json` nella directory di lavoro esatta.
4. Il valore predefinito globale impostato da `beeuni projects use`.

| Comando | Effetto |
| --- | --- |
| `beeuni projects ls [--all] [--query <text>] [--json]` | Elenca i progetti dell'account attivo. `--all` include tutti gli account di cui fai parte. `--query` (alias `-q`) filtra per nome, ID o repository. |
| `beeuni projects info [<id>] [--json]` | Mostra un progetto. Predefinito: il progetto collegato o quello predefinito. |
| `beeuni projects use [<id>]` | Imposta il progetto predefinito globale. Se il progetto si trova in un altro account, passa a quell'account. |
| `beeuni projects unset` | Cancella il progetto predefinito globale. |
| `beeuni projects link [<id>]` | Collega la directory corrente a un progetto. Scrive `.beeuni/link.json`. |
| `beeuni projects unlink` | Rimuove `.beeuni/link.json`. |
| `beeuni projects open [<id>]` | Apre nel browser la pagina della dashboard di un progetto. |
| `beeuni projects clone [<id>] [dir]` | Clona il repository di un progetto tramite il proxy Git autenticato di Beeuni. |
| `beeuni projects rm [<id>] [-y\|--yes]` | Elimina un progetto e il relativo repository Git gestito da Beeuni. I repository collegati autonomamente non vengono mai modificati. |
| `beeuni projects set [<id>] [--name <n>] [--branch <b>] [--manifest <path>] [--json]` | Aggiorna le impostazioni di un progetto. Vengono scritti solo i campi specificati. Se non specifichi alcun campo, esce da `2`. Alias: `update`. |
| `beeuni projects set [<id>] --icon <emoji>\|--no-icon\|--glyph <name>:<color>\|--no-glyph` | Imposta o rimuove l'icona del progetto. |
| `beeuni projects rename [<id>] <name>` | Alias di `beeuni projects set --name <name>`. |
| `beeuni projects features [ls] [--json]` | Elenca tutti i flag delle funzionalità con chiave, stato, origine e livello di stabilità. |
| `beeuni projects features enable\|disable\|reset <flag>` | Imposta l'override del progetto su attivo o disattivo, oppure lo cancella affinché il flag segua il valore predefinito della piattaforma. |
| `beeuni projects cli-tokens ls [--json]` | Elenca i token CLI del progetto. |
| `beeuni projects cli-tokens new [--name <name>] [--expires-at <iso>]` | Crea un token CLI associato al progetto. Il segreto viene mostrato una sola volta. |
| `beeuni projects cli-tokens rm <token-id> [-y\|--yes]` | Revoca un token CLI del progetto. |
| `beeuni projects upgrade [<id>] [--json]` | Avvia la sessione dell'agente che migra un `beeuni.toml` v1 a un `beeuni.yaml` v2 e apre una richiesta di modifica. |

Un progetto mostra una sola icona: scrivendo `--icon` si cancella il glifo e scrivendo `--glyph` si cancella l'emoji; non è consentito specificarli entrambi. Colori dei glifi: `grey`, `red`, `orange`, `yellow`, `lime`, `blue`, `purple`, `magenta`. Per `set` e `features` serve `project.settings.write`. Un flag che la piattaforma contrassegna come non disponibile resta disattivato, indipendentemente dall'override del progetto.

Un token CLI del progetto è associato a un solo progetto: l'API lo rifiuta ovunque altro. Un ambiente sandbox di sessione usa il proprio `BEEUNI_TOKEN` associato alla sessione. Per `cli-tokens ls` serve l'accesso in lettura al progetto; per `new` e `rm` serve `project.credentials.issue`. Un token associato a una sessione non può creare né revocare token del progetto (`403`), indipendentemente dal fatto che il progetto dichiari degli agenti. Un token CLI del progetto segue le regole PAT dell'account: se l'account richiede una scadenza, specifica `--expires-at`; una scadenza oltre la durata massima restituisce `400`.

`beeuni projects upgrade` richiede l'accesso in scrittura al progetto. L'agente predefinito aggiorna la versione di riferimento del marketplace, riscrive il manifesto, esegue `beeuni validate` e apre una richiesta di modifica. Non esegue mai il merge: la differenza viene revisionata da una persona.

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

### Struttura iniziale del progetto

`beeuni init [project-name] [options]` crea una nuova directory di progetto. Il modello iniziale genera un `beeuni.yaml` v2, `agents/`, `skills/`, `memory/` e `harnesses/opencode/`. Il comando può configurare il rilevamento degli strumenti di programmazione locali senza modificare il runtime predefinito. Il comando non scrive `.beeuni/link.json`. `beeuni ship` o `beeuni projects link` creano quel file.

| Flag | Significato |
| --- | --- |
| `--name <project>` | Nome del progetto. |
| `--primary <agent>` | Agente principale. |
| `--agents <csv>` | Integrazioni degli agenti di programmazione locali da configurare. |
| `--force` | Configura la directory corrente senza creare una nuova struttura iniziale. |
| `--overwrite` | Sovrascrive i file esistenti. |
| `--no-git` | Salta l'inizializzazione di Git. |
| `-y, --yes` | Non richiede conferma. |

La selezione degli strumenti di programmazione locali non modifica il runtime predefinito.

`beeuni init` non include un selettore di marketplace. Per aggiungere una competenza dal marketplace, chiedi all'agente di importarla avviando una sessione.

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

### Pubblicazione

`beeuni ship` prepara, esegue il commit e invia il branch corrente al repository Git del progetto. Eseguilo una volta per creare il progetto. Eseguilo di nuovo in qualsiasi momento per sincronizzare le modifiche. Alias: `beeuni deploy`.

A ogni esecuzione:
- Esegue i controlli [`beeuni validate`](#manifest-validation): `beeuni.yaml` unito a ogni file elencato in [`imports:`](/docs/it/project/manifest#imports), ai Dockerfile delle sandbox, al collegamento degli agenti e alle dimensioni del repository (salta con `--no-verify`). Un errore interrompe la pubblicazione. Un avviso non la interrompe mai.
- Esegue il commit di eventuali modifiche non salvate nell'albero di lavoro (salta con `--no-commit`).
- Chiede eventuali secret `env` mancanti (salta con `--no-env`).
- Esegue il push del branch corrente sul branch remoto con lo stesso nome.
- Connette tutti i connettori dichiarati che richiedono ancora l'autenticazione (salta con `--no-connect`).

Un `origin` GitHub esistente viene collegato tramite l'app GitHub di Beeuni. Qualsiasi altro `origin` esistente viene registrato così com'è. Se non è presente alcun `origin`, viene creato un repository Git gestito da Beeuni.

| Opzione | Effetto |
| --- | --- |
| `--name <project>` | Nome visualizzato per un nuovo progetto. |
| `--account <id\|slug>` | Account in cui creare il progetto (solo al primo ship). |
| `--origin <managed\|git-url>` | Sovrascrive la scelta dell'origine dedotta. |
| `--github-token <pat>` | Collega un'origine GitHub con questo token invece che con l'app GitHub. |
| `-m, --message <text>` | Messaggio di commit. |
| `--no-commit` / `--no-verify` / `--no-env` / `--no-connect` | Salta quel passaggio. |
| `-y, --yes` | Non chiedere conferma. |
| `-n, --dry-run` | Mostra cosa accadrebbe senza apportare modifiche. |
| `--project <id>` / `--host <name>` | Scegli un progetto o un host non predefinito. |

<a id="apps"></a>

### App

Apps ospita siti statici, server, processi e database. Ogni App ha un URL stabile. Una release contiene codice e configurazione; una distribuzione fallita non sostituisce la release attiva.

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

Collega le App con `uses` e gli esempi di `beeuni apps connect`. Non inserire credenziali amministrative nel codice client.

Le risorse attive consumano crediti dell’account. Controlla Billing e Usage. Apps non ha un budget mensile separato.

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

### Sessioni

Ogni sessione viene eseguita in una sandbox sul proprio branch.

| Comando | Effetto |
| --- | --- |
| `beeuni sessions ls [--mine\|--shared\|--automated] [--search <q>] [--label <label>]... [--json]` | Elenca le sessioni. `--label` può essere ripetuto; una sessione deve avere tutte le etichette specificate. La colonna LABELS viene visualizzata se una delle sessioni elencate ha delle etichette. |
| `beeuni sessions status [--all] [--json]` | Tutte le sessioni e cosa sta facendo in questo momento il relativo agente. Alias: `overview`, `ps`. |
| `beeuni sessions info <id> [--json]` | Vista dettagliata: stato, branch, agente, URL della sandbox. |
| `beeuni sessions new [--prompt "<text>"] [--agent <name>] [--model <id>] [--wait] [--connect] [--json]` | Avvia una sessione. `--connect` apre l'interfaccia TUI del runtime predefinito quando è pronta (implica `--wait`); in un terminale interattivo, se non è specificato, la CLI chiede se connettersi dopo la creazione. `--model <id>` sostituisce il modello predefinito del progetto; un modello che usa una chiave API o un abbonamento ChatGPT usa tutte le chiavi che puoi usare per quel modello, alternandole. `--wait` attende finché non è in esecuzione (fino a ~5 minuti). Usa `--secret <id>` o `--no-secrets` per limitare l'accesso ai Secret. Questi flag per i Secret richiedono un token backend. Usa `--connector <alias>=<authorization-id>` o `--no-connectors` per impostare l'accesso ai Connector. Usa `--require-connector <alias>` per richiedere un'autorizzazione prima del provisioning. I flag di ambito possono essere ripetuti. Usa `--context <key>=<value>` per il contesto runtime non segreto. `--label <label>` (ripetibile) classifica la sessione; `--meta <key>=<value>` (ripetibile) memorizza una stringa nei metadati. |
| `beeuni sessions chat [<id>] [--prompt "<text>"] [--queue \| --steer] [--new] [--agent <name>] [--json]` | Comunica con l'agente di una sessione. Interattivo per impostazione predefinita. Alias: `talk`. È disponibile anche `beeuni chat` di primo livello. `--queue` è solo per un singolo messaggio: salva il prompt nella casella di posta persistente della sessione e termina non appena viene salvato, senza passarlo al runtime. `--steer` lo salva allo stesso modo e il turno in corso lo legge al passaggio successivo, senza interrompersi. Se non è in corso alcun turno, ne avvia uno. Una sessione che non può essere guidata lo esegue come `--queue`. |
| `beeuni sessions connect [<id>] [-- <opencode args>]` | Collega l'interfaccia TUI del runtime predefinito al server del runtime predefinito della sessione. Disponibile anche al primo livello: `beeuni connect` / `beeuni attach`. Se non si specifica un ID, apre un selettore di sessioni (in esecuzione, arrestata con riavvio o nuova). La CLI scarica automaticamente il binario `opencode` della versione corrispondente (cache: `~/.beeuni/opencode/<version>/`; sostituzione: `BEEUNI_OPENCODE_BIN`). Una sessione pi non ha un server opencode: il comando termina con `1` e indica invece `beeuni sessions shell` e `beeuni sessions chat`. |
| `beeuni tui [--host <name>] [--project <id>] [--session <id>] [--new] [--agent <name>] [--terminal] [--no-sidebar] [--mouse] [--install] [--uninstall]` | **Sperimentale.** Apri il client terminale Beeuni: sessioni, trascrizione, compositore, shell sandbox, Files, Review, Apps, Customize e Account. Alias `beeuni t` e `beeunit`. `--new` crea una sessione nel progetto all'avvio (`--agent` seleziona l'agente), `--terminal` apre la shell sandbox già selezionata, `--no-sidebar` avvia senza barra laterale (`Alt+B` la mostra o nasconde), `--mouse` cede il controllo del mouse all'app (disattivato per impostazione predefinita, così continuano a funzionare la selezione, la copia e i clic sui link del terminale). La TUI è un binario separato di ~80 MB; al primo avvio chiede conferma, poi installa `beeuni-tui` della versione corrispondente in `~/.beeuni/tui/<version>/`; gli aggiornamenti successivi della CLI lo aggiornano senza chiedere e riutilizzano il binario se non è cambiato. `--install` lo installa senza chiedere, `--uninstall` lo rimuove. Usa l'host attivo, a meno che `--host` non ne indichi un altro; se non è stato effettuato l'accesso a nessun host, apre la propria schermata di accesso. `?` mostra tutte le associazioni di tasti. Vedi [/docs/cli#sessions](/docs/it/cli#sessions). |
| `beeuni sessions shell [<id>] [--new]` | Apri un terminale interattivo puro nella sandbox, senza agente. Si ricollega al terminale esistente della sessione; `--new` ne avvia sempre uno nuovo. Alias: `terminal`, `ssh`. |
| `beeuni sessions shell <id> ls [--json]` | Elenca i terminali della sessione: ID, stato, comando. Non richiede un TTY. |
| `beeuni sessions shell <id> kill <pty-id>` | Termina un terminale. La shell di base viene riavviata al collegamento successivo; ciò che è in esecuzione al suo interno no. |
| `beeuni sessions forward <id> --port <sandbox>[:<local>]` | Inoltra una porta della sandbox al tuo computer, come in VS Code, così `http://localhost:3000` stampato da un agente funziona nel tuo browser. `--port` può essere ripetuto; se non si specifica una porta locale, viene usato lo stesso numero se disponibile, altrimenti la successiva porta libera; `:0` richiede una porta effimera assegnata dal sistema operativo. Vengono inoltrati sia HTTP sia WebSocket (il ricaricamento automatico del server di sviluppo funziona). Stampa una riga `⇄ localhost:N → sandbox:M` per ogni inoltro e resta in primo piano finché non premi Ctrl+C. Non avvia una sessione arrestata: stampa invece la soluzione `beeuni sessions restart`. Alias: `ports`. |
| `beeuni sessions log [<id>] [--limit <n>] [--json]` | Stampa i messaggi recenti in sola lettura. Una sessione in esecuzione viene letta in tempo reale; una sessione arrestata viene letta dalla trascrizione salvata al termine di ogni turno, quindi non viene mai riattivata solo per leggerla. La fonte è indicata su stderr, perciò l'output di `--json` rimane invariato. Alias: `messages`, `history`. |
| `beeuni sessions attachments <id> [--download <attachment-id>\|--all] [--out <dir>] [--json]` | Elenca e scarica i file salvati di una sessione: quelli allegati dagli utenti e le copie dei file mostrati dall'agente. Funziona anche se la sessione è arrestata: né l'elenco né i file richiedono la sandbox. I download non sovrascrivono i file esistenti; un nome già in uso diventa `name (1).ext`. |
| `beeuni sessions pending <id> [--json]` | Elenca le richieste aperte di autorizzazione agli strumenti o le domande. Alias: `prompts`. |
| `beeuni sessions approve <id> [<req-id>] [--always] [--reject] [--message "<text>"]` | Risponde a una richiesta di autorizzazione. |
| `beeuni sessions answer <id> [<req-id>] [--option <v>]... [--text "<text>"] [--reject]` | Risponde a una domanda. |
| `beeuni sessions digest [--since <7d>] [--json]` | Panoramica compatta per rivedere più sessioni. La trascrizione di una sessione arrestata proviene dalla copia salvata ed è contrassegnata con `saved` (e `partial` se la copia non arriva al primo messaggio). Alias: `review`, `summary`. |
| `beeuni sessions scope <id> [scope options] [--json]` | Legge o sostituisce l'accesso a Secret e Connector. Alias: `access`. Usa `--secret <id>`, `--no-secrets` o `--inherit-secrets` per i Secret. Usa `--connector <alias>=<authorization-id>` o `--no-connectors` per le associazioni ai Connector. Usa `--require-connector <alias>` o `--no-required-connectors` per i Connector obbligatori. Le categorie indicate sostituiscono i valori attuali. Le categorie omesse rimangono invariate. Le modifiche si applicano al prompt successivo. I valori Secret rimossi restano nel contesto esistente se la sessione li aveva già letti. |
| `beeuni sessions preview <id> [port] [--port <n>] [--list] [--json]` | Stampa un URL di anteprima cliccabile per una porta della sandbox. Porta predefinita: `3000`. `--list` stampa invece i candidati specificati. |
| `beeuni sessions restart <id>` | Riavvia la sandbox della sessione. |
| `beeuni sessions rename <id> <name>` | Imposta il nome di una sessione. Passa `""` per cancellarlo. |
| `beeuni sessions update [<id>] [--label <l>]... [--unlabel <l>]... [--clear-labels] [--meta <key>=<value>]... [--unmeta <key>]... [--json]` | Modifica le etichette e i metadati di una sessione. `--label` aggiunge, `--unlabel` rimuove, `--clear-labels` svuota prima l'elenco; `--meta` imposta una chiave stringa, `--unmeta` rimuove una chiave. Se non si specifica un ID, aggiorna `$BEEUNI_SESSION_ID`, consentendo a un agente di etichettare la sessione in cui è in esecuzione. Alias: `label`. |
| `beeuni sessions rm <id>...` | Arresta ed elimina una o più sessioni. |
| `beeuni sessions open <id>` | Apre nel browser la pagina del dashboard di una sessione. |
| `beeuni sessions stop <id> [--json]` | Mette in pausa una sessione. La sandbox si arresta senza essere rimossa e il disco viene conservato. Alias: `pause`. Richiede `project.session.stop`. |
| `beeuni sessions start <id> [--wait] [--json]` | Riattiva una sessione: crea una sandbox se manca, riprende quella arrestata e risolve il runtime. È idempotente. Alias: `wake`. `--wait` attende finché non è pronta (fino a ~5 min) e termina con `1` se la sessione finisce in stato di errore o arrestata. |
| `beeuni sessions warm [--exclude <id>] [--json]` | Crea in anticipo la sessione che stai per usare, così la sandbox è già pronta. Riutilizza una sessione warm esistente e inutilizzata. Una sessione warm resta nascosta da `sessions ls` fino al primo prompt. |
| `beeuni sessions model <id> <model-id> [--json]` | Cambia il modello usato da una sessione durante la sessione. Se la sandbox è attiva, viene reindirizzata e il runtime si riavvia, terminando il turno in corso; se la sessione è arrestata, il valore viene salvato per il prossimo avvio. Una sessione senza chiavi selezionate per il provider del nuovo modello riceve tutte le chiavi che puoi usare con quel provider. |
| `beeuni sessions compact <id> [--json]` | Riassume la conversazione finora e continua dal riepilogo. Una sessione il cui runtime non elenca `session.compact` esce con `1` come motivo. |
| `beeuni sessions queue <id> [ls] [--json]` | Elenca i prompt ancora in attesa nella casella di posta persistente della sessione. |
| `beeuni sessions queue <id> rm <prompt-id>` | Elimina un prompt in coda. L'operazione viene rifiutata (`409`) una volta che un passaggio del modello ha iniziato a rispondervi. |
| `beeuni sessions queue <id> now <prompt-id>` | Esegui per primo un prompt in coda: rimettilo in coda prima degli altri e rilascia il blocco della sessione. |
| `beeuni sessions queue <id> hold\|release` | Blocca tutti i prompt in coda — ciò che scrive il pulsante Stop — oppure rilascia il blocco. |
| `beeuni sessions approvals <id> [ls] [--json]` | Elenca le chiamate ai connettori soggette a policy per cui questa sessione attende l'intervento umano. |
| `beeuni sessions approvals <id> approve\|deny <execution-id>` | Consenti l'esecuzione di una chiamata a un connettore soggetta a policy oppure rifiutala. L'agente ne viene informato e continua senza di essa. |
| `beeuni sessions files <id> <subcommand> [--json]` | Leggi e modifica l'area di lavoro attiva della 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]` | Imposta chi, all'interno di Beeuni, può aprire questa sessione. Se non si specifica `--mode`, mostra l'impostazione corrente senza modificarla. `--member` e `--group` possono essere ripetuti. |
| `beeuni sessions links <id> ls [--json]` | Elenca tutti i link pubblici mai creati per la sessione, dal più recente al meno recente. |
| `beeuni sessions links <id> create [options]` | Crea un link pubblico senza autenticazione per una porta di anteprima o un file dell'area di lavoro. |
| `beeuni sessions links <id> revoke <share-id>` | Disattiva un link pubblico. |

`sessions queue` richiede `project.session.start`, lo stesso permesso necessario per inviare un messaggio. Un prompt in coda resta disponibile anche dopo la chiusura del terminale e viene consegnato quando la sessione è in grado di riceverlo. Inseriscine uno con `beeuni sessions chat <id> -p "…" --queue` oppure orienta il turno in corso con `--steer`. `sessions queue ls` mostra `DELIVERY` di ogni prompt (`steer`, `queue` o `interrupt`) e, per un prompt di reindirizzamento eseguito come `queue`, il motivo: `unsupported` (la sessione non può ricevere messaggi durante un turno), `not_prompter` (è in corso il turno di un altro membro) o `turn_ended`.

`sessions approvals` sono persistenti: a differenza di `sessions pending`, sopravvivono al riavvio della sandbox. Per usarli serve `project.members.manage` oppure essere la persona che ha avviato la sessione. Un agente non può mai risolvere una propria approvazione.

`sessions attachments` legge l'archivio privato di file della sessione, non la sua area di lavoro. I file vi vengono salvati al momento dell'invio e tutti i file mostrati dall'agente vi vengono salvati al termine del turno.

`sessions files` legge l'albero di lavoro che l'agente sta modificando in quel momento, prima che venga eseguito un commit; `beeuni files` legge invece il repository con i commit. I percorsi vengono risolti in `/workspace`, a meno che non inizino con `/workspace`, `/tmp`, `/home` o `/opt`. Il comando riattiva la sandbox se è inattiva. Opzioni: `--from <local path>` (`write` legge questo file invece di stdin), `--content` (`find` cerca nei contenuti con ripgrep invece che nei nomi dei file), `--limit <N>` (limite di nomi file `find`) e `-y` per saltare la conferma `rm`.

`sessions share` è soggetto al controllo del proprietario: l'API rifiuta la richiesta di un responsabile di progetto che non abbia già accesso in lettura alla sessione. Una sessione condivisa viene eseguita solo con chiavi del provider condivise con l'intero progetto: un modello che usava le tue chiavi personali passa alle chiavi del progetto per quel provider; se nesbeeuni chiave del progetto consente di eseguirlo, la condivisione viene rifiutata (`409 SHARED_SESSION_NEEDS_PROJECT_KEY`).

Opzioni di `sessions links create`: `--port <n>` (predefinito `3000`; `22`, `8000` e le porte di opencode vengono rifiutate), `--path <p>` (predefinito `/`), `--preview <id>` (un candidato specifico — `web`, `vite`, `dev-server`, `api-docs` — invece di `--port`/`--path`), `--file <path>` (condividi un file dell'area di lavoro invece di un'anteprima; sempre in sola lettura), `--mode view\|interactive` (predefinito `view`; `interactive` consente scritture e websocket ed è ignorato per `--file`), `--label <text>` e `--expires <iso>`. Per creare un link serve il proprietario della sessione, perché il link non richiede accesso; per elencare e revocare i link è sufficiente anche un responsabile di progetto.

All'interno di una sandbox, `BEEUNI_SESSION_ID` è l'id della propria sessione.

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

### Richieste di modifica

Una richiesta di modifica (CR) unisce un branch a un altro su qualsiasi hosting Git. È l'unico modo in cui un agente può portare il lavoro svolto nella sessione nel branch predefinito. Vedi [Richieste di modifica](/docs/it/work/change-requests).

| Comando | Effetto |
| --- | --- |
| `beeuni cr ls [--status open\|merged\|closed\|all] [--project <id>]` | Elenca le CR. Valore predefinito: `--status open`. |
| `beeuni cr show <cr> [--project <id>]` | Mostra una CR, inclusa l'anteprima dell'unione. Alias: `info`. |
| `beeuni cr diff <cr> [--no-color] [--json]` | Stampa il diff unificato di una CR. |
| `beeuni cr open --title "<text>" [--description "<text>"] [--head <ref>] [--session <id>] [--base <ref>]` | Apre una CR. Alias: `new`, `create`. All'interno di una sandbox, `--head` e `--session` vengono impostati automaticamente. `--base` è il branch predefinito del progetto. |
| `beeuni cr merge <cr> [--message "<text>"]` | Unisce una CR aperta. Usa il fast-forward quando possibile, altrimenti un'unione a tre vie. |
| `beeuni cr close <cr>` | Chiude una CR aperta senza unirla. |
| `beeuni cr reopen <cr>` | Riapre una CR chiusa. Le CR unite non possono più essere modificate. |
| `beeuni cr merge-preview <cr> [--json]` | Indica se la CR può essere unita ed elenca tutti i percorsi in conflitto. Alias: `preview`. |
| `beeuni cr request-changes <cr> --message "<text>"` | Chiede all'agente che ha aperto la CR di modificarla. Alias: `changes`. |
| `beeuni cr version-diff --from <ver> --into <ver> [--json]` | Riassume una versione rispetto a un'altra prima di aprire una CR. |

`request-changes` registra la nota sulla CR e la invia alla sessione di origine, riavviando la sandbox se è inattiva. Richiede `project.review.act`, lo stesso permesso specifico usato dal Review Center, non `gitops.push`.

`<cr>` accetta un numero specifico del progetto (`3`) oppure l'id completo. All'interno di una sandbox, la CLI legge automaticamente il token: non serve accedere né usare un link.

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

### Revisione

La casella di revisione del progetto contiene tutto ciò che attende una decisione umana: richieste di modifica, chiamate a strumenti dei connettori bloccate da una policy in attesa di approvazione, nonché output, decisioni e batch inviati dagli agenti per l'approvazione. Rispecchia il Review Center della dashboard. È attiva per tutti i progetti; `project.review.read` e `project.review.act` controllano la lettura e l'esecuzione delle azioni.

| Comando | Effetto |
| --- | --- |
| `beeuni review ls [--segment <s>] [--kind <k>] [--json]` | Elenca gli elementi in attesa. Valore predefinito: tutti i segmenti. |
| `beeuni review show <item-id> [--json]` | Mostra per intero un elemento. |
| `beeuni review act <item-id> <verdict> [--message <text>]` | Decide l'esito di un elemento. `--message` include la nota. |
| `beeuni review bulk <verdict> <id> [<id> …]` | Decide l'esito di più elementi nativi con una sola chiamata. |
| `beeuni review submit --kind <k> --title <t> [options]` | Invia un output, una decisione o un batch per la revisione. |

Esiti: `approve`, `reject`, `changes`, `answer`, `dismiss`. Segmenti: `needs_you`, `waiting`, `done`. Tipi: `change`, `approval`, `output`, `decision`, `batch`.

L'effetto dell'esito dipende dall'id dell'elemento. Per `cr:<id>`, `approve` esegue l'unione della modifica, `reject` la chiude e `changes` invia la nota all'agente che l'ha aperta (è richiesto `--message`). Per `call:<id>`, `approve` consente l'esecuzione della chiamata allo strumento e `reject` la rifiuta; un'approvazione del connettore non ammette altri esiti: prima esamina gli argomenti con `beeuni review show`. Per tutti gli altri id viene usato l'endpoint nativo delle azioni, che accetta ogni esito.

`bulk` agisce solo sugli id nativi. Le approvazioni dei connettori richiedono di esaminare i relativi parametri e le richieste di modifica richiedono di visualizzare il diff: entrambe vengono segnalate e ignorate, come avviene con la selezione multipla nella dashboard.

Opzioni di `submit`: `--kind output\|decision\|batch` (obbligatorio), `--title <text>` (obbligatorio), `--summary <text>`, `--risk none\|low\|medium\|high` (valore predefinito `none`), `--detail <json>` (un oggetto JSON), `--agent <name>` e `--session <id>` (ignorato se non si riferisce a una sessione di questo progetto).

Per leggere serve `project.review.read`, per esprimere un verdetto serve `project.review.act` e `submit` richiede `project.review.submit`.

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

### Segreti

Valori cifrati archiviati nel progetto. Per impostazione predefinita, all'avvio un segreto viene iniettato come variabile d'ambiente in chiaro in ogni sandbox di sessione (esposizione tramite ambiente). La consegna vincolata — in cui la sandbox conserva un riferimento e Beeuni sostituisce il valore reale al di fuori di essa (esposizione vincolata in uscita e `beeuni secrets call`) — è sperimentale. Attiva il flag di funzionalità `secrets_egress` (Settings → Feature flags) per usarla; se il flag è disattivato, `beeuni secrets delivery … egress` restituisce `403` `feature_disabled`. Vedi [Secrets](/docs/it/project/secrets).

| Comando | Effetto |
| --- | --- |
| `beeuni secrets ls` | Elenca i segreti per identificatore e specifica del manifest `env`, indicando chi può usare ciascun valore. Segnala i valori obbligatori mancanti. |
| `beeuni secrets set NAME=VALUE ... [--identifier <id>] [--scope runtime\|connector] [--only-me]` | Crea o aggiorna uno o più segreti. `NAME=-` legge il valore da stdin. `--scope connector` conserva il valore lato server per il gateway del connettore. `--only-me` rende il nuovo valore utilizzabile solo da te. |
| `beeuni secrets share IDENTIFIER --user <email\|id\|me> --group <id> --agent <name> \| --everyone` | Imposta chi può usare il valore. Le persone vi accedono direttamente o nelle proprie sessioni private; un agente può farlo in ognuna delle sue sessioni, incluse quelle avviate da trigger. Vedi [Who can use a secret](/docs/it/project/secrets#who-can-use-a-secret). |
| `beeuni secrets request NAME ... [--scope runtime\|connector] [--expires <min>]` | Crea un link che consente a una persona di inserire un valore che non possiedi. |
| `beeuni secrets unset NAME ...` | Rimuove i segreti. |
| `beeuni secrets grant IDENTIFIER --agent <name>` | Consente a un agente di ricevere questo segreto: aggiunge l'identificatore all'elenco `secrets` dell'agente in `beeuni.yaml`, aggiungendo la voce dell'agente se il manifest non la contiene. |

`grant` serve a correggere una riga che `ls` segnala come non recapitabile. Può solo ampliare l'elenco di un agente; per restringerlo o sostituirlo, riscrivi l'intero insieme con `beeuni
agents scope`. There is no `secrets revoke` — l'API non ha un endpoint per rimuovere un singolo identificatore da un'autorizzazione. La prima autorizzazione concessa in un progetto senza agenti avvia la governance: da quel momento, un agente non elencato nel manifest non riceve i segreti del progetto e il comando lo segnala quando accade.

### Env

| Comando | Effetto |
| --- | --- |
| `beeuni env pull [--out <path>] [--force]` | Scrive uno scheletro `.env` — solo nomi. I valori non lasciano mai il cloud. |
| `beeuni env push --from <path>` | Carica ogni `NAME=VALUE` da un file dotenv come segreto. |

### Agents

Impostazioni del modello per agente nel progetto collegato.

| Comando | Effetto |
| --- | --- |
| `beeuni agents ls [--json]` | Mostra il modello fissato per ogni agente e il valore predefinito di riserva. Alias: `models`. |
| `beeuni agents model <agent> <provider/model>` | Fissa un modello per un agente. |
| `beeuni agents model <agent> --clear` | Rimuove il modello fissato: l'agente torna a seguire il valore predefinito. |
| `beeuni agents default <agent>` | Imposta questo agente come predefinito del progetto. |
| `beeuni agents default --show [--json]` | Stampa l'agente predefinito corrente. |
| `beeuni agents scope <agent> [--secrets all\|none\|A,B] [--connectors all\|none\|a,b] [--apps all\|none\|a,b] [--require-connector <slug>]` | Sostituisce l'insieme di segreti, connettori e Beeuni Apps che l'agente può usare. `--apps` accetta gli slug delle App e richiede un `beeuni.yaml` v2; l'agente deve avere anche `project.app.read`. `--require-connector` può essere ripetuto e deve essere risolto prima dell'avvio di una sessione. |
| `beeuni agents scope <agent> --show [--json]` | Stampa l'ambito corrente dell'agente. |
| `beeuni agents config <agent> [--json]` | Stampa il blocco di configurazione completo dell'agente. |
| `beeuni agents config <agent> --file <path>` | Sostituisce il blocco con il contenuto di un file JSON. `-` legge da stdin. |
| `beeuni agents config <agent> --set <key>=<value> ...` | Modifica singole chiavi con notazione a punti, applicando le modifiche. Ripetibile, ad es. `behavior.model=glm-5.3-flash`, `enabled=false`, `connectors=["slack"]`. |

Ogni opzione di ambito sostituisce i valori; nesbeeuni li unisce. Un valore `--set` viene interpretato come JSON se è valido, altrimenti viene mantenuto come stringa. I modelli fissati e `scope` si applicano immediatamente, senza commit di `beeuni.yaml`; `default` e `config` eseguono il commit su `beeuni.yaml` nel ramo predefinito del progetto. `scope` richiede `project.agent.write`, così come `default` e `config`.

### Tools

Gli strumenti disponibili nelle sessioni del progetto, letti dal file locale `beeuni.yaml` e dai relativi [import](/docs/it/project/manifest#imports). Esegui dalla radice del progetto. Vedi [Tools](/docs/it/project/tools).

| Comando | Effetto |
| --- | --- |
| `beeuni tools ls [--json]` | Elenca ogni strumento disponibile nelle sessioni: nome, tipo (`beeuni`, `beeuni (overridden)`, `project`) e origine (`beeuni:<name>` o il percorso del modulo). Elenca anche gli strumenti Beeuni rimossi dal progetto. `--json` stampa `{ manifest, tools_key, tools, removed }`. |
| `beeuni tools eject <name> [--force]` | Copia lo strumento Beeuni `<name>` in `tools/<name>.ts` e imposta `tools.<name>: tools/<name>.ts` in `beeuni.yaml`, nel file che lo dichiara. La riga modificata termina con `# ejected from beeuni:<name>`; tutti gli altri commenti restano invariati. Se non è presente la chiave `tools:`, elenca anche gli altri quattro strumenti Beeuni, così l'espulsione non rimuove nulla. Si rifiuta di procedere se esiste `tools/<name>.ts` o se lo strumento punta già a un altro modulo, a meno che non sia specificato `--force`. Rifiuta un nome che non corrisponde a uno strumento Beeuni. |

Se non è presente la chiave `tools:`, ogni sessione riceve tutti e cinque gli strumenti Beeuni (`web_search`,
`image_search`, `scrape_webpage`, `memory`, `show`). Se è presente la chiave `tools:`,
le sessioni ricevono solo gli strumenti Beeuni elencati. Per rimuovere uno strumento Beeuni, elimina la relativa riga sotto `tools:`, poi esegui `beeuni validate`. Per limitare gli strumenti di un singolo agente, usa `agents.<name>.tools`. Codici di uscita: `0` completato, `1` operazione rifiutata (un file esiste, oppure un manifest o un import non è analizzabile), `2` manifest mancante, opzione sconosciuta o nome che non corrisponde a uno strumento Beeuni.

### Models

Quali modelli offre il progetto e quale usa all'avvio. Stessa schermata di Customize → Models nel dashboard. Un progetto memorizza solo le eccezioni al valore predefinito del catalogo (il modello più recente di ogni famiglia). L'abilitazione è solo visiva: determina cosa mostrano i selettori, non cosa fornisce il gateway.

| Comando | Effetto |
| --- | --- |
| `beeuni models ls [--json]` | Elenca tutti i modelli utilizzabili: stato, origine, modalità di pagamento (`VIA`: Beeuni, chiave API o ChatGPT — personale, condivisa con te o condivisa con il progetto), provider. |
| `beeuni models enable <model-id>...` | Rende disponibili questi modelli. |
| `beeuni models disable <model-id>...` | Smette di offrire questi modelli. Il modello predefinito del progetto viene rifiutato con `409`: cambia prima il valore predefinito. |
| `beeuni models reset` | Rimuove tutte le eccezioni e ripristina i valori predefiniti del catalogo. |
| `beeuni models default [--json]` | Stampa la catena dei valori predefiniti (progetto → account → piattaforma) e il risultato della risoluzione. |
| `beeuni models default <model-id> [--account]` | Imposta il valore predefinito del progetto o quello dell'intero account con `--account`. |
| `beeuni models default --clear [--account]` | Cancella il valore predefinito del progetto o dell'account. |

Gli ID modello sono ID wire del gateway — un ID gestito semplice (`glm-5.3-flash`) o un `provider/model` BYOK. Copiane uno da `beeuni models ls --json`. I modelli fissati per agente sono in `beeuni agents model <agent> <model-id>`. Le modifiche richiedono
`project.model.write`.

### Channels

Gestisce la connessione del progetto a una piattaforma di chat. I token sono archiviati cifrati nei segreti del progetto e risolti lato server: non vengono mai iniettati nella sandbox.

| Comando | Effetto |
| --- | --- |
| `beeuni channels status [--json]` | Mostra la connessione corrente. |
| `beeuni channels connect [--wait] [--timeout <sec>]` | Connette in un solo passaggio: stampa un link di installazione. `--wait` verifica finché l'installazione non viene completata. |
| `beeuni channels connect --manual [--bot-token <token>] [--signing-secret <secret>]` | Modalità di app personalizzata: salva direttamente un token bot e un segreto di firma. |
| `beeuni channels disconnect [--platform slack\|teams]` | Rimuove la connessione del progetto: quella Slack oppure quella Teams con `--platform teams`. |
| `beeuni channels manifest` | Stampa il JSON del manifest dell'app per la modalità con app personalizzata. |
| `beeuni channels email status [--json]` | Gestisce la casella di posta e la modalità di consegna di un connettore email. |
| `beeuni channels email connect [options]` | Crea una casella di posta gestita oppure collega una casella AgentMail esistente. |
| `beeuni channels email disconnect` | Rimuove la connessione alla casella di posta. |
| `beeuni channels email policy [--allow <email\|@domain>] [--allow-regex <re>] [--allow-all]` | Sostituisce l'elenco di chi può inviare email all'agente. |
| `beeuni channels bindings [ls] [--json]` | Elenca tutti i canali associati e l'agente, il modello e la policy di accesso a cui ciascuno viene risolto. |
| `beeuni channels bind <bindingId> [--agent <name>\|--no-agent] [--model <id>\|--no-model] [--policy <p>]` | Modifica un'associazione. `--policy` accetta `owner_approval`, `owner_only` o `project_open`. |

`--platform slack|teams` seleziona la piattaforma; predefinita: `slack`. Teams
`connect` stampa l'URL di consenso amministrativo Microsoft; concedendo il consenso a livello di tenant,
l'app viene pubblicata automaticamente nel catalogo di Teams. Vedi [Connettori](/docs/it/connect/connectors).

Il canale email è basato su AgentMail e richiede il flag della funzionalità `agentmail_email`.
Opzioni `email connect`: `--connector <slug>` (predefinita `beeuni_email`),
`--api-key <k>` (usa la tua chiave AgentMail; `-` legge da stdin),
`--display-name <n>` (nome mittente per le email in uscita; per impostazione predefinita, il nome del progetto),
`--username <u>` e `--domain <d>` (una nuova casella gestita) e
`--inbox-id <id>` con `--email <addr>` (collega una casella esistente: entrambi sono
obbligatori). `--allow` è ripetibile e attiva la modalità con restrizioni; un
valore senza `@` o con `@` iniziale viene interpretato come dominio.
`--allow-all` cancella l'elenco e consente nuovamente tutti i mittenti.

Le scritture email e `bind` richiedono `project.connector.write`.

<a id="connectors"></a>

### Connettori

Connettori che un agente usa come strumenti. `add`, `rm` e `policy set` modificano il file locale `beeuni.yaml`; esegui `beeuni ship` per applicare le modifiche, a meno che tu non passi `--apply` per modificare immediatamente il progetto cloud.

| Comando | Effetto |
| --- | --- |
| `beeuni connectors ls [--json]` | Elenca i connettori e il loro stato. |
| `beeuni connectors show <slug> [--json]` | Mostra gli strumenti di un connettore. |
| `beeuni connectors add <slug> --provider <p> [options] [--apply]` | Aggiunge un connettore. |
| `beeuni connectors rm <slug> [--apply]` | Rimuove un connettore. |
| `beeuni connectors rename <slug> <name>` | Imposta il nome visualizzato di un connettore. |
| `beeuni connectors sync` | Riconcilia il catalogo con il file `beeuni.yaml` incluso. |
| `beeuni connectors credential <slug> [value]` | Imposta le credenziali di un connettore. |
| `beeuni connectors connect <slug>` | Avvia una procedura di connessione in un clic. |
| `beeuni connectors link <slug> [--expires <min>]` | Crea un link di connessione condivisibile per una persona. |
| `beeuni connectors types [--connector <a,b>] [--out <file>]` | Scrive i tipi TypeScript per ogni azione invocabile: un file `declare module '@beeuni/sdk'` che definisce i tipi degli argomenti `connectors.callAction(slug, action, args)` e di `output`. I connettori gestiti non pubblicano schemi di output, quindi il risultato è `unknown`. Senza `--out`, stampa su stdout. |
| `beeuni connectors accounts <slug> [--default <label\|id>] [--json]` | Elenca gli account con cui possono essere eseguite le chiamate e l'identità usata per ciascuna connessione. `--default` ne imposta uno. |
| `beeuni connectors connections ls [--all] [--json]` | Elenca le connessioni con etichetta, `CONNECTED AS`, proprietario, `WHO CAN USE` (`owner only`, `everyone` o le etichette di concessione, con `(not you)` quando la connessione è elencata solo per gestirla), stato e valore predefinito. |
| `beeuni connectors connections rename <id> <label…>` | Rinomina una connessione. Cambia solo l'etichetta; non è necessaria una nuova autorizzazione. |
| `beeuni connectors connections share <id> [--group <id>]… [--user <email\|id>]… [--everyone]` | Condivide il tuo account privato: diventa un account condiviso che solo quella persona può usare (`--everyone`: l'intero progetto). Richiede il diritto di gestire le connessioni del progetto. |
| `beeuni connectors apps [<query>] [--category <c>] [--cursor <c>] [--limit <n>] [--json]` | Cerca nel catalogo dei toolkit gestiti, gli slug accettati da `add --provider composio --app <slug>`. Alias: `beeuni connectors toolkits`. Aggiungi `--pipedream` per il catalogo legacy. |
| `beeuni connectors catalog [<query>] [--cursor <c>] [--json]` | Esplora il catalogo dei connettori diretti. Richiede il flag `connectors_api_discover`. |
| `beeuni connectors catalog show <id> [--json]` | Mostra le interfacce di un record del catalogo. |
| `beeuni connectors sensitive <slug> on\|off` | Sottopone ad approvazione anche le letture di questo connettore: ogni chiamata richiede quindi l'approvazione. Si applica subito. |
| `beeuni connectors owner <slug> project\|user` | Chi autorizza: una connessione del progetto oppure l'account di ciascun membro. Si applica subito. |
| `beeuni connectors authorize <slug> [--status] [--scope "<a b>"] [--client-id <id>] [--client-secret <s>] [--success-redirect <url>] [--error-redirect <url>] [--json]` | Configura OAuth 2.1 per un connettore dall'inizio alla fine: individua i metadati di autorizzazione del server, registra Beeuni come client (RFC 7591) se supportato dal server e stampa l'URL da approvare. `--status` mostra invece il risultato. |
| `beeuni connectors authorize <slug> --device` | Come sopra, usando il flusso OAuth 2.0 per dispositivi (RFC 8628): stampa un codice e un URL, poi controlla finché la richiesta non viene approvata, rifiutata o scade. |
| `beeuni connectors policy ls [--json]` | Mostra i criteri di esecuzione validi per l'intero progetto. Alias: `show`. |
| `beeuni connectors policy set --default <risk\|allow_all> [--apply]` | Imposta la modalità di esecuzione predefinita in `beeuni.yaml`. `--apply` la imposta subito. |
| `beeuni connectors policy add <match> <allow\|ask\|block> [--condition <k=v>]` | Aggiunge una regola valida per l'intero progetto. Si applica subito. `--condition` la restringe a un argomento corrispondente ed è ripetibile; `k!=v` nega la corrispondenza e `k` è un percorso con punti negli argomenti della chiamata. |
| `beeuni connectors policy rm <match>` | Rimuove una regola valida per l'intero progetto. Si applica subito. |
| `beeuni connectors policy <slug> ls\|set <match> <allow\|ask\|block>\|rm <match>\|clear` | Gestisce le regole per le chiamate agli strumenti di un connettore. |

`policy ls`, `show`, `set`, `add` e `rm` sono comandi che agiscono sull'intero progetto: perciò, un connettore che ha lo stesso nome di uno di questi verbi va indicato come `policy <slug> ls`. Un `<match>` è il nome di uno strumento, un glob (`send_*`) o un `/regex/`.

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

<a id="sandboxes"></a>

### Sandbox

Gestisce le immagini sandbox del progetto. Un modello definisce un'immagine o un Dockerfile e le risorse; una build crea lo snapshot da cui vengono avviate le sessioni.

| Comando | Effetto |
| --- | --- |
| `beeuni sandboxes ls [--json]` | Elenca i modelli e lo stato attuale del provider. |
| `beeuni sandboxes builds [--json]` | Registro delle build recenti. |
| `beeuni sandboxes health [--json]` | Stato di disponibilità del modello principale. |
| `beeuni sandboxes add <slug> (--image <i>\|--dockerfile <p>) [options]` | Crea un modello personalizzato e avvia una build. |
| `beeuni sandboxes update <slug> [options]` | Aggiorna un modello. |
| `beeuni sandboxes build <slug>` | Avvia una nuova build. |
| `beeuni sandboxes rebuild <slug>` | Forza una nuova build: elimina prima lo snapshot esistente. |
| `beeuni sandboxes rm <slug>` | Elimina un modello. |
| `beeuni sandboxes fix` | Avvia una sessione con il registro dell'ultima build non riuscita, per correggere il problema. |
| `beeuni sandboxes provider [--json]` | Mostra il provider sandbox fissato per il progetto e i provider disponibili su questo host. |
| `beeuni sandboxes provider <name> [--timeout <sec>]` | Fissa tutte le nuove sessioni a un provider. Se la destinazione richiede prima la creazione dello snapshot, l'API risponde con una preparazione e il comando ne attende il completamento. Valore predefinito di `--timeout`: 600s. |
| `beeuni sandboxes provider --clear` | Rimuove il vincolo e usa il valore predefinito della piattaforma. Alias: `--unpin`. |
| `beeuni sandboxes provider status [--json]` | Mostra la transizione più recente del provider e la relativa cronologia. Alias: `transition`. |

Fissare un provider richiede `project.settings.write`.

Opzioni `add`/`update`: `--name <label>`, `--cpu <n>`, `--memory <n>` (GiB), `--disk <n>` (GiB).

<a id="backends"></a>

### Backend

I database sono App con volumi persistenti. Gestiscili e collegali tramite Apps.

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

### Marketplace

Esplora il marketplace di Beeuni e installa un elemento in un progetto.

| Comando | Effetto |
| --- | --- |
| `beeuni marketplace search [query]` | Cerca elementi nel marketplace. |
| `beeuni marketplace list` | Elenca gli elementi del marketplace. |
| `beeuni marketplace show <id-or-name>` | Mostra un elemento del marketplace. |
| `beeuni marketplace install <id-or-name>` | Avvia una sessione dell'agente che importa l'elemento. |

Opzioni: `--query <text>`, `--type <type>`, `--source <source>`, `--host <name>`, `--project <id>`, `--json`.

L'installazione è gestita dall'agente: avvia una sessione del progetto che clona l'elemento,
lo legge, integra ciò che è compatibile e apre una richiesta di modifica. Non esiste alcun
meccanismo deterministico per installare, aggiornare o rimuovere elementi.

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

### Competenze di sistema

Le competenze di sistema di Beeuni sono il riferimento operativo della piattaforma per persone e agenti. Coprono sessioni, sandbox, il runtime predefinito, connettori, memoria e canali. Questa pagina pubblica è il punto di ingresso; la CLI autenticata legge le competenze dall'host in esecuzione. Usa `beeuni system-skills list` per scoprire le competenze disponibili, poi `get` quella necessaria. L'API le fornisce in tempo reale, quindi corrispondono alla versione dell'host distribuita. Non considerare aggiornata una copia locale.

| Comando | Effetto |
| --- | --- |
| `beeuni system-skills list` | Elenca le competenze di sistema di Beeuni. Sottocomando predefinito. |
| `beeuni system-skills get <name> [--full]` | Stampa `SKILL.md` corrente di una competenza. `--full` aggiunge i file a cui fa riferimento. |
| `beeuni system-skills path [name]` | Stampa la directory su disco di una competenza in questo progetto. |

Opzioni: `--host <name>`, `--json`.

`beeuni skills` è un alias permanente dello stesso comando. Accedi prima all'host con `beeuni login`; l'API delle competenze richiede l'autenticazione. Usa `--host <name>` quando lavori con un altro host. Una pagina di documentazione pubblica non può sostituire queste istruzioni aggiornate e specifiche dell'host.

Questo elenco contiene sempre le competenze di sistema, mai un insieme misto. Le competenze facoltative si trovano nel marketplace: `beeuni marketplace list --type skill`. Per la sintassi dei comandi, usa `beeuni <command> --help`; per il riferimento completo della piattaforma, leggi `beeuni system-skills get beeuni-system --full`.

<a id="connector"></a>

### Connettore

L'interfaccia dell'agente nella sandbox per ogni connettore. Ogni chiamata viene verificata, risolta e sottoposta ad audit lato server; la CLI non conserva mai credenziali di terze parti. Autenticazione: `BEEUNI_TOKEN`. L'output è JSON.

| Comando | Effetto |
| --- | --- |
| `beeuni connectors discover "<intent>"` | Cerca strumenti in base all'intento espresso in linguaggio naturale. |
| `beeuni connectors show <connector>.<action>` | Mostra lo schema di input di un'azione. |
| `beeuni connectors call <connector>.<action> '<json-args>'` | Esegue uno strumento. Una chiamata soggetta a controllo restituisce immediatamente il suo `approval_url` autenticato. Il server riprende la sessione dopo una decisione di approvazione o rifiuto. Passa gli argomenti di grandi dimensioni come `@file.json` o `-` (stdin). |
| `beeuni connectors call <connector>.<action> '<json-args>' --reason "<text>"` | Descrive all'approvatore umano cosa fa la chiamata quando una policy la mette in attesa. La scheda di approvazione mostra questa descrizione dell'agente accanto agli argomenti. |
| `beeuni connectors call <connector>.<action> @args.json --attach <file>` | Prepara un file e aggiunge il relativo riferimento all'array degli allegati dell'azione. Il gateway scrive i byte nell'elemento degli allegati del provider. `--attach` ripete l'operazione; `--attach-path <a.b.c>` indica l'array. Vedi [Allegare file](/docs/it/connect/connectors#attach-files). |
| `beeuni connectors call <connector>.<action> '<json-args>' --out <file>` | Scrive il risultato JSON completo in `<file>` e stampa solo un riepilogo: `saved_to`, `bytes` e `shape` (chiavi, lunghezze degli array, `pageInfo`). Vedi [Risultati di grandi dimensioni](/docs/it/connect/connectors#large-results). |
| `beeuni connectors upload <file> --connector <slug>` | Prepara un file. Stampa `ref`, `{"$beeuni_attachment":"<id>"}`, da inserire negli argomenti della chiamata. |
| `beeuni connectors add <slug> --provider pipedream --app <app>` | Aggiunge immediatamente un connettore, quindi lo connette. |
| `beeuni connectors rm <slug>` | Rimuove un connettore dal progetto. |
| `beeuni connectors connect <slug> [--owner me\|project] [--label <name>]` | Genera un link di connessione per una persona. `--label` suggerisce un nome per un nuovo account, ad esempio un secondo account Gmail. |

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

### File

Vista in sola lettura del repository git del progetto. Opera sul branch predefinito, a meno che `--ref` non specifichi un altro branch, tag o commit.

| Comando | Efeito |
| --- | --- |
| `beeuni files ls [<path>]` | Lista recursivamente os arquivos em um caminho. 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 as branches. |
| `beeuni files commits [--path <p>]` | Lista os 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 referências. |
| `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 para 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`. Além disso, `download` recusa qualquer
subárvore que inclua um agente ou uma skill fora do seu escopo — não é possível filtrar um 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 com base em um agendamento, webhook, evento de app ou monitor (experimental). `add`, `rm`, `enable` e `disable` editam o manifesto local — execute `beeuni ship` para aplicar. `pause`/`resume` alternam um controle separado no servidor. Consulte [Gatilhos](/docs/it/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. Só as flags informadas são gravadas. Sempre aplica as alterações imediatamente — não há versão local. Alias: `update`. |
| `beeuni triggers rm <slug> [--apply]` | Remove um gatilho de `beeuni.yaml` ou do projeto na nuvem imediatamente 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 termina com código diferente de zero e exibe o erro; a sessão nova criada pelo 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 todos os `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 loops; deve ser uma sessão deste projeto), `--session-access <private\|project\|members>` (padrão `private`), `--member <uuid>` e `--group <uuid>` (podem ser repetidas; cada uma implica `members`), e `--filter <path=value>` (pode ser repetida; todas 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 exclusivas: definir uma limpa a outra. Os campos do monitor só podem ser adicionados.

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

### Lembretes

Um lembrete envia um novo prompt para uma sessão mais tarde, uma vez ou de forma recorrente. Ele é armazenado no banco de dados, não em `beeuni.yaml`. Dentro de uma sessão, `--session` tem como padrão `$BEEUNI_SESSION_ID`. Consulte [Lembretes](/docs/it/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 agendamento: `--in <duration>` ou `--at <iso>` (primeiro disparo; se usado sozinho, dispara uma vez), `--every <duration>` (recorrência, mínimo de `5m`), `--cron "<expr>"` com `--timezone <tz>`. Outras opções: `--name <label>`, `--session <id>` (um prefixo exclusivo 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 string) e `--config-json '{...}'` (valores tipados). `set` aceita as mesmas flags. 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/it/connect/triggers#app-event-triggers).

Opções de monitor (`--type monitor`): `--run <cmd>` (comando relativo ao repositório a ser monitorado; 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 30s, por exemplo `60s`, `5m`) e `--expect-event-within <dur>` (watchdog de silêncio; se nenhum evento ocorrer dentro do intervalo, dispara um evento de ciclo de vida; mínimo de 5m, por exemplo `24h`). Um monitor é um comando do repositório que a plataforma executa 24 horas por dia, 7 dias por semana, e cada linha de stdout dispara o gatilho. É experimental: a plataforma executa monitores somente onde a feature flag `monitors` está ativada.

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

### Acesso

A interface de linha de comando da tabela única de concessões. Cada linha é uma **atribuição**: um
principal, uma função, um escopo e, opcionalmente, um objeto específico. Consulte
[Contas e acesso](/docs/it/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 a 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; recebe um `--agent` ou um `--connection`, nunca uma função) e `--expires <iso>` (timestamp 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 para todos é exibida 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 email 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 membros do projeto são uma visão de leitura das mesmas atribuições:

| Comando | Efeito |
| --- | --- |
| `beeuni access ls [--json]` | Lista as pessoas com acesso ao projeto, a função da 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 um e-mail de convite e renova sua validade por 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, concedendo 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 vinculações](/docs/it/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
por horário de criação (`session_sequence` só é definido nas linhas gravadas antes de 2026-10, que 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 de auditoria](/docs/it/accounts#retention)). A tabela mostra
junto a cada linha o título (`EVENT`, por exemplo, "Chave do gateway LLM revogada") e 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/it/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>` | Retoma cada página da exportação em um único 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 uma entrega de teste é enviada imediatamente. `--action-prefix` entrega somente ações com esse prefixo. |
| `beeuni audit webhooks enable <webhook-id>` | Retoma a entrega. |
| `beeuni audit webhooks disable <webhook-id>` | Pausa a entrega, mantendo o endpoint. |
| `beeuni audit webhooks rm <webhook-id>` | Exclui um webhook permanentemente. |

Os webhooks de auditoria transmitem o registro para um SIEM. Todos os verbos precisam de `account.write`;
`add` e `enable` também exigem o direito de uso enterprise. `disable` e `rm`
nunca exigem.

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 uso `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 uma sessão 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 de objeto) são referências somente leitura. Você pode criar e editar funções
personalizadas, que exigem o direito de uso enterprise `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. Exige `role.update` e não aceita funções 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 as funções e atribuições para um arquivo. |
| `beeuni roles import <file>` | Aplica um arquivo de funções e atribuições. |

Vincule 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 caminho documentado. `beeuni roles actions` foi substituído
por `beeuni permissions ls`.

Uma função personalizada apenas adiciona permissões. O Beeuni não tem regras de negação, portanto 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, como dados. Uma linha por ação final, com o escopo em que ela é
avaliada, 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` usam
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 de objeto**. Os segredos e
conectores ficam nos agentes; portanto, atribuir um agente a uma pessoa concede tudo o que
esse agente declara. Por padrão, o acesso a um agente é fechado: um membro só pode acessá-lo quando
uma atribuição o identifica pelo nome ou identifica um grupo ao qual pertence. `beeuni access grant --agent
<name>` grava a mesma linha.

| Comando | Efeito |
| --- | --- |
| `beeuni grants ls [--json]` | Lista as atribuições de 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 de 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, analisa com lint cada Dockerfile da sandbox e a configuração dos agentes e verifica o tamanho do repositório. Resolve primeiro `beeuni.yaml` 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 esquema JSON do manifesto. `--url` exibe o URL do esquema. |

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

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

#### Tamanho do repositório

Uma sessão cria a [configuração do agente](/docs/it/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, independentemente do tamanho. Uma sessão em execução recebe as alterações na branch base por meio do snapshot do projeto, que o Beeuni Cloud cria 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. Todas as sessões também baixam todos os arquivos. `beeuni validate` contabiliza os arquivos armazenados pelo Git, além dos arquivos não rastreados que `beeuni ship` adicionará em seguida, e exibe um aviso quando um arquivo tiver 10 MiB ou mais ou o total ultrapassar 512 MiB. Um arquivo do Git LFS é contabilizado como seu ponteiro, pois a versão inclui apenas o ponteiro. O aviso indica os arquivos maiores. Ele nunca faz o comando falhar.

Para eliminar o aviso:
- Mova recursos 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 o exclui, assim como a verificação; uma regra de diretório abrange tudo o que estiver dentro dele. O diretório de configuração do agente e `beeuni.yaml` sempre são incluídos por inteiro.

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

### Escopo do token

Ogni token inizia con `beeuni_pat_`. Un token utente è valido per tutti i progetti dei tuoi account. Un token di progetto è valido per un solo progetto e viene inserito automaticamente nelle sandbox di quel progetto. Consulta il riferimento completo alla famiglia di token in [Runtime della sessione](/docs/it/work/runtime).

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

### Codici di uscita

| Codice | Significato |
| --- | --- |
| `0` | Operazione riuscita. |
| `1` | Operazione non riuscita. I messaggi diagnostici vengono stampati su stderr. |
| `2` | Flag non valido, sottocomando sconosciuto o argomento obbligatorio mancante. |