AI nativa

Lavora a un progetto Beam con il tuo agente

Beam CLI consente a un agente esterno di esaminare e modificare veri progetti Screenshot e video. Chiedigli di leggere il documento, apportare una modifica e controllare il risultato. Lo stesso progetto resta modificabile in Beam.

• Modifica i contenuti nativi: taglia o sposta clip, regola zoom e sfondi oppure disponi livelli, gruppi ed effetti di Screenshot.
• Crea contenuti grafici HTML e TypeScript, usando eventualmente Vue, GSAP o WebGL, e pubblicali come livello.
• Controlla la tela live, annulla una modifica ed esporta con il renderer di Beam.

Configura il launcher della riga di comando

Usa il launcher beam-cli incluso con Beam. Da un checkout del codice sorgente, sostituisci beam-cli con bun run beam ed esegui il comando dalla radice del repository. Inizia elencando gli strumenti e leggendo i relativi schemi; questi comandi di individuazione funzionano senza l’app desktop.

Le chiamate agli strumenti accettano JSON in linea, un file di argomenti preceduto dal simbolo chiocciola oppure un trattino per il JSON da stdin. I risultati vanno su stdout; gli errori su stderr con un codice di uscita diverso da zero. Gli esempi in linea usano le regole di quoting POSIX. Su Windows, i file di argomenti evitano differenze di quoting della shell. I percorsi in un file vengono risolti rispetto alla sua cartella; i percorsi in linea rispetto alla directory di lavoro.

beam-cli tools list
beam-cli tools describe html.publish
beam-cli docs agent
beam-cli docs html
beam-cli docs gradients
beam-cli docs commands
beam-cli commands

Installa le skill di Beam

Apri un terminale nel progetto in cui lavora l’agente, quindi installa le skill. La destinazione predefinita è .agents/skills all’interno del progetto. Non viene installato nulla globalmente, a meno che tu non specifichi esplicitamente --global. In seguito ricarica le skill dell’agente o avvia una nuova sessione.

Il pacchetto include dieci skill specializzate. Installale tutte con il comando seguente oppure aggiungi i nomi per selezionarne un sottoinsieme, ad esempio beam-cli beam-design beam-composition beam-animation. Per una cartella specifica dell’agente, usa --agent claude, --agent cursor o --agent gemini; anche queste rimangono all’interno del progetto corrente. Se la CLI installata non riconosce ancora le skill, usa una build più recente di Beam CLI o bun run beam da un checkout aggiornato del codice sorgente Beam.

beam-cli skills install

Controlla e aggiorna le skill

Esegui questi comandi dalla stessa cartella del progetto. check confronta i file installati con il pacchetto in BeamRecorder/Beam senza apportare modifiche. Il rapporto JSON indica le skill aggiornate, mancanti, obsolete, modificate o in conflitto; restituisce il codice di uscita 1 se una skill selezionata non è aggiornata. update scarica il pacchetto corrente, incluse le skill mancanti, e protegge le modifiche locali.

Il pacchetto mantenuto si trova in .skills/Beam-cli nel repository GitHub di Beam. I file vengono verificati prima dell’installazione. Gli aggiornamenti sono espliciti: i normali comandi di modifica non controllano la presenza di nuove skill. Usa --ref con un tag o un commit per fissare una versione e consulta la documentazione delle skill per cartelle personalizzate e modifiche locali protette.

beam-cli skills check
beam-cli skills update
beam-cli docs skills

Apri il progetto e leggine lo stato

Avvia Beam, quindi elenca i progetti. L’esempio crea una tela Screenshot trasparente. Sostituisci PROJECT_UUID con l’id restituito, aprilo e attendi che projects.list includa quell’id in open. Quindi richiedi documents.snapshot per il documento e la revisione correnti.

Per Studio, usa kind: video sia per la creazione che per l’apertura. projects.open apre normalmente un nuovo editor; disposition: reuse sostituisce l’editor attivo. Se sono in esecuzione più istanze di Beam, aggiungi --instance PID usando un id ottenuto da instances.

beam-cli instances
beam-cli tools call projects.list
beam-cli tools call projects.create '{"kind":"image","name":"Feature card","width":1920,"height":1080}'
beam-cli tools call projects.open '{"projectId":"PROJECT_UUID","kind":"image"}'
beam-cli tools call documents.snapshot '{"projectId":"PROJECT_UUID"}'

Modifica un livello Screenshot

Usa questo esempio con un progetto di immagine acquisita, non con la tela vuota creata sopra. Salvalo come edit.json e sostituisci SCREENSHOT_UUID e expectedRevision con i valori di documents.snapshot. Il livello sorgente acquisito ha id image; la transazione lo rinomina e aggiunge un’inclinazione 3D.

Trova gli id degli altri livelli nello snapshot. L’interfaccia dei comandi supporta posizionamento, ritaglio, raggruppamento, ordine, colore, effetti e impostazioni PNG/WebP. Leggi lo schema del payload prima di modificare. Un array effects sostituisce l’intera pila, quindi includi gli effetti esistenti che vuoi conservare.

{
  "projectId": "SCREENSHOT_UUID",
  "expectedRevision": 0,
  "operationId": "screenshot-perspective-1",
  "commands": [
    {
      "type": "still.layer.rename",
      "payload": {
        "layerId": "image",
        "name": "Product capture"
      }
    },
    {
      "type": "still.layer.compositing",
      "payload": {
        "layerId": "image",
        "patch": {
          "rotation3d": {
            "x": 6,
            "y": -12,
            "perspective": 1200
          }
        }
      }
    }
  ]
}

Modifica una clip video esistente

Per un progetto video che contiene una clip, usa invece questa transazione come edit.json. Sostituisci VIDEO_UUID, expectedRevision e CLIP_ID con i valori di uno snapshot aggiornato. Imposta la sfocatura dello sfondo e sposta la clip al secondo 1 della timeline.

I comandi video includono anche taglio, divisione, velocità di riproduzione, volume, sottotitoli, elementi, gruppi di scene, animazione delle proprietà e zoom. assets.import copia i contenuti multimediali nel progetto; in seguito usa i comandi del documento per posizionarli nella timeline.

{
  "projectId": "VIDEO_UUID",
  "expectedRevision": 0,
  "operationId": "video-layout-1",
  "commands": [
    {
      "type": "render.patch",
      "payload": {
        "blurPercent": 12
      }
    },
    {
      "type": "clip.move",
      "payload": {
        "clipId": "CLIP_ID",
        "startMs": 1000
      }
    }
  ]
}

Applica una transazione

Applica edit.json al progetto descritto. I comandi costituiscono un’unica modifica atomica e un solo passaggio di annullamento: se il gruppo non è valido, non viene applicata alcuna modifica parziale. I contenuti bloccati restano protetti.

Assegna a ogni nuova modifica un nuovo operationId. Riutilizza un id solo per ripetere una richiesta identica. Puoi annullare in Beam oppure chiamare documents.undo/documents.redo con expectedRevision corrente e un requestId univoco.

beam-cli tools call documents.transact @edit.json

Crea una scheda HTML statica

Crea composition/index.html con l’esempio seguente. Mantieni localmente font, stili e contenuti multimediali. HTML e TypeScript funzionano senza Vue; installa eventuali librerie importate in questo progetto sorgente.

Una scheda statica non richiede un clock di animazione. Beam attende il caricamento dei font locali e la decodifica delle immagini. Per l’inizializzazione asincrona, esponi una promise ready su window.beamComposition.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <style>
      html, body { margin: 0; width: 100%; height: 100%;
        overflow: hidden; background: transparent; }
      .card { position: absolute; inset: 100px; padding: 80px;
        border-radius: 40px; background: #151517; color: white;
        font: 64px sans-serif; }
    </style>
  </head>
  <body><div class="card">Beam feature</div></body>
</html>

Prepara la richiesta di pubblicazione

Salva publish.json accanto alla cartella della composizione. Usa l’id e la revisione corrente del progetto Screenshot aperto. Larghezza e altezza sono le dimensioni in pixel della tela HTML. Le pubblicazioni Screenshot richiedono durationMs: 0. Usa framework: html oppure vue per una sorgente Vue.

{
  "projectId": "SCREENSHOT_UUID",
  "expectedRevision": 0,
  "entry": "./composition/index.html",
  "width": 1920,
  "height": 1080,
  "durationMs": 0,
  "framework": "html",
  "name": "Feature card"
}

Aggiungi la scheda a Beam

html.publish compila la sorgente, ne archivia sorgente e bundle nel progetto e inserisce un livello HTML. Restituisce layerId e la nuova revisione. Un progetto Screenshot salva anche un PNG renderizzato di quel livello.

Per una nuova versione della stessa scheda, mantieni in publish.json il layerId restituito e aggiorna expectedRevision. L’aggiornamento conserva posizionamento, ordine dei livelli, visibilità ed effetti. Le versioni pubblicate della sorgente restano disponibili nel progetto riaperto e nella cronologia di annullamento.

beam-cli tools call html.publish @publish.json

Anima un livello video con un clock posizionabile

Per animare la scheda per cinque secondi, installa GSAP nel relativo progetto sorgente e salva il codice seguente come composition/main.ts. Aggiungi in index.html uno script modulo per ./main.ts. In publish.json, usa l’id di un progetto video aperto, durationMs: 5000 e fps: 30. Rimuovi il layerId di Screenshot prima della prima pubblicazione nel video.

Esponi window.beamComposition.seek(timeMs). Beam richiede istanti precisi in millisecondi e può spostarsi all’indietro. Mantieni GSAP in pausa e imposta esplicitamente il tempo della timeline. Con Vue, attendi gli aggiornamenti reattivi; con WebGL, disegna il fotogramma completato. seek può restituire una promise per la preparazione asincrona.

import { gsap } from 'gsap';

const timeline = gsap.timeline({ paused: true });
timeline.fromTo('.card',
  { opacity: 0, y: 80 },
  { opacity: 1, y: 0, duration: 1 }, 0);
timeline.to('.card', { scale: 1.05, duration: 3 }, 1);
timeline.to('.card', { opacity: 0, duration: 1 }, 4);

Object.assign(window, {
  beamComposition: {
    seek(timeMs: number) {
      timeline.time(timeMs / 1000, false);
    },
  },
});

Visualizza in anteprima i salvataggi della sorgente in Beam

Mantieni in publish.json un layerId esistente e avvia html watch. Pubblica una volta, legge la revisione live prima degli aggiornamenti successivi e ripubblica dopo ogni salvataggio della sorgente. Ctrl+C interrompe il monitoraggio. Un errore di compilazione o revisione lascia disponibile il livello pubblicato in precedenza.

Per recuperare il codice di un livello salvato, chiama html.source con il descrittore HTML di documents.snapshot. Copia la sorgente archiviata in una cartella di lavoro prima di modificarla; le versioni pubblicate della sorgente sono immutabili. L’anteprima può accorpare le richieste, mentre l’esportazione renderizza ogni fotogramma richiesto della timeline.

beam-cli html watch @publish.json

Importa immagini e font

• Conserva immagini e font locali nella cartella sorgente oppure fornisci voci references con i campi name e source. Beam copia questi file nella cartella references accanto al file HTML.
• Per fare riferimento a un contenuto multimediale di un altro progetto salvato, includi projectId. assets.resolve individua un file del progetto da esaminare; html.publish può copiarlo nel bundle.
• Usa il testo nativo se vuoi modificarne il contenuto in Beam: still.layer.add per Screenshot oppure clip.insert per gli elementi video. Il testo all’interno dell’HTML si modifica nel codice sorgente.
• fonts.import accetta TTF, OTF, WOFF e WOFF2. Imposta text.style.fontFamily e text.style.fontAssetId sulla famiglia e sull’id restituiti, così il testo modificabile usa quel font nell’anteprima e nell’esportazione.

beam-cli tools call fonts.list
beam-cli tools call fonts.import '{"source":"./fonts/HankenGrotesk.ttf"}'

Esamina ed esporta il risultato

Installa una volta il backend Chromium della CLI oppure imposta BEAM_CHROMIUM_EXECUTABLE su un browser compatibile. Durante l’esportazione di un progetto aperto con livelli HTML, lascia Beam in esecuzione: fornisce i fotogrammi renderizzati. Sostituisci gli id sotto e scegli un istante compreso nella durata del video.

Screenshot usa le impostazioni PNG/WebP del documento; fai corrispondere l’estensione dell’output al formato. Video supporta MP4 e WebM con livelli, sottotitoli e zoom della composizione. Per sostituire intenzionalmente una destinazione esistente, passa overwrite: true.

beam-cli browser install
beam-cli tools call render.export '{"projectId":"SCREENSHOT_UUID","output":"feature.png"}'
beam-cli tools call render.export '{"projectId":"VIDEO_UUID","output":"demo.mp4","format":"mp4"}'
beam-cli tools call render.frame '{"projectId":"VIDEO_UUID","timeMs":2000,"output":"frame.png"}'

Modifica un file immagine senza l’app desktop

Inizia da un PNG esistente e dalle sue dimensioni effettive. Salva solo l’array commands della transazione Screenshot come edits.json, quindi crea, modifica ed esporta il documento autonomo seguente. Questo flusso di lavoro modifica un documento file, non un editor Beam aperto.

Le operazioni standalone edit e serve non richiedono l’app desktop. L’esportazione richiede il backend Chromium della CLI. Per un video HTML senza editor, usa motion con un file job; beam-cli docs html descrive entry, dimensioni, durata in secondi, fps e formato.

beam-cli create image capture.png 1920 1080 screenshot.json
beam-cli edit screenshot.json edits.json edited-screenshot.json
beam-cli export edited-screenshot.json finished.png

Scopri cosa viene eseguito localmente

La CLI si collega all’app desktop tramite un endpoint locale autenticato. Beam esegue il rendering localmente. L’HTML pubblicato viene eseguito in finestre isolate, senza accesso a Node né preload di Beam; le richieste alla rete esterna sono bloccate, quindi includi le risorse localmente nel bundle.

L’agente e il modello sono forniti da te. La gestione dei dati dipende dal provider scelto. Beam fornisce gli strumenti per i documenti e l’interfaccia di rendering; non include un abbonamento a una chat AI, un server MCP stdio o la modifica condivisa in rete.