AI native

Work on a Beam project with your agent

Beam CLI lets an external agent inspect and edit real Screenshot and video projects. Ask it to read the document, make a change and inspect the result. The same project remains editable in Beam.

• Edit native content: trim or move clips, adjust zooms and backgrounds, or arrange Screenshot layers, groups and effects.
• Create HTML and TypeScript artwork, optionally using Vue, GSAP or WebGL, and publish it as a layer.
• Review the live canvas, undo an edit and export with Beam’s renderer.

Set up the command-line launcher

Use the beam-cli launcher included with Beam. From a source checkout, replace beam-cli with bun run beam and run from the repository root. Start by listing tools and reading their schemas; these discovery commands work without the desktop app.

Tool calls accept inline JSON, an argument file prefixed with an at sign, or a dash for JSON from stdin. Results go to stdout; errors go to stderr with a nonzero exit code. Inline examples use POSIX quoting. On Windows, argument files avoid shell-quoting differences. Paths in a file resolve beside it; inline paths resolve from the working directory.

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

Install the Beam skills

Open a terminal in the project where your agent works, then install the skills. The default destination is .agents/skills inside that project. Nothing is installed globally unless you explicitly pass --global. Reload the agent’s skills or start a new session afterward.

The pack includes ten focused skills. Install them all with the command below, or append names to select a subset, such as beam-cli beam-design beam-composition beam-animation. For an agent-specific folder, use --agent claude, --agent cursor or --agent gemini; these also stay inside the current project. If your installed CLI does not recognize skills yet, use a newer Beam CLI build or bun run beam from an up-to-date Beam source checkout.

beam-cli skills install

Check and update the skills

Run these commands from the same project folder. check compares the installed files with the pack in BeamRecorder/Beam and changes nothing. Its JSON report identifies current, missing, outdated, modified or conflicting skills; it exits with code 1 when any selected skill is not current. update downloads the current pack, including missing skills, and leaves your local edits protected.

The maintained pack lives in .skills/Beam-cli on Beam’s GitHub repository. Files are verified before installation. Updates are explicit; normal editing commands do not check for new skills. Use --ref with a tag or commit when you need a pinned version, and read docs skills for custom folders and protected local changes.

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

Open the project and read its state

Start Beam, then list projects. The example creates a transparent Screenshot canvas. Replace PROJECT_UUID with its returned id, open it and wait until projects.list includes that id in open. Then request documents.snapshot for the current document and revision.

For Studio, use kind: video for both creation and opening. projects.open normally opens a new editor; disposition: reuse replaces the active editor. If more than one Beam instance is running, append --instance PID using an id from 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"}'

Edit a Screenshot layer

Use this example with a captured-image project, not the empty canvas created above. Save it as edit.json and replace SCREENSHOT_UUID and expectedRevision with values from documents.snapshot. The captured source layer has the id image; the transaction renames it and adds a 3D angle.

Find other layer ids in the snapshot. The command interface supports placement, crop, grouping, ordering, color, effects and PNG/WebP settings. Read the payload schema before editing. An effects array replaces the entire stack, so include existing effects you want to keep.

{
  "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
          }
        }
      }
    }
  ]
}

Edit an existing video clip

For a video project containing a clip, use this transaction as edit.json instead. Replace VIDEO_UUID, expectedRevision and CLIP_ID from a fresh snapshot. It sets background blur and moves the clip to one second on the timeline.

Video commands also cover trimming, splitting, playback rate, volume, captions, elements, scene groups, property animation and zooms. assets.import copies media into the project; use document commands to place it on the timeline afterward.

{
  "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
      }
    }
  ]
}

Apply a transaction

Apply edit.json to the project it describes. The commands form one atomic edit and one undo step: if the batch is invalid, no partial edit is committed. Locked content remains protected.

Give each new edit a new operationId. Reuse an id only for an identical retry. You can undo in Beam or call documents.undo/documents.redo with the current expectedRevision and a unique requestId.

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

Create a static HTML card

Create composition/index.html with the example below. Keep fonts, styles and media local. HTML and TypeScript work without Vue; install any imported libraries in this source project.

A static card needs no animation clock. Beam waits for local fonts and image decoding. For asynchronous initialization, expose a ready promise on 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>

Prepare the publication request

Save publish.json beside the composition folder. Use your open Screenshot project’s id and current revision. Width and height are the HTML canvas dimensions in pixels. Screenshot publications require durationMs: 0. Use framework: html, or vue for a Vue source.

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

Add the card to Beam

html.publish compiles the source, stores its source and bundle in the project and inserts an HTML layer. It returns layerId and the new revision. A Screenshot project also stores a rendered PNG of that layer.

For another version of the same card, keep the returned layerId in publish.json and refresh expectedRevision. Updating preserves placement, layer order, visibility and effects. Published source versions remain available to the reopened project and undo history.

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

Animate a video layer with a seekable clock

To animate the card for five seconds, install GSAP in its source project and save the code below as composition/main.ts. Add a module script for ./main.ts to index.html. In publish.json, use an open video project id, durationMs: 5000 and fps: 30. Remove the Screenshot layerId before the first publication into this video.

Expose window.beamComposition.seek(timeMs). Beam requests exact times in milliseconds and can seek backward. Keep GSAP paused and set its timeline time explicitly. With Vue, wait for reactive updates; with WebGL, draw the completed frame. seek may return a promise for asynchronous preparation.

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);
    },
  },
});

Preview source saves in Beam

Keep an existing layerId in publish.json and start html watch. It publishes once, reads the live revision before subsequent updates and republishes after source saves. Ctrl+C stops the watcher. A compile or revision error leaves the previous published layer available.

To return to a saved layer’s code, call html.source with the HTML descriptor from documents.snapshot. Copy that stored source into a working folder before editing it; published source versions are immutable. Preview can coalesce requests, while export renders each requested timeline frame.

beam-cli html watch @publish.json

Bring in images and fonts

• Keep local images and fonts in the source folder, or supply references entries with name and source fields. Beam copies these files under references beside the HTML.
• For a project-media reference from another saved project, include its projectId. assets.resolve locates a project-owned file for inspection; html.publish can copy it into the bundle.
• Use native text when you want to edit the wording in Beam: still.layer.add for Screenshot, or clip.insert for video elements. Text inside HTML is edited through its source code.
• fonts.import accepts TTF, OTF, WOFF and WOFF2. Set text.style.fontFamily and text.style.fontAssetId to the returned family and id so editable text uses that font in preview and export.

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

Inspect and export the result

Install the CLI Chromium backend once, or point BEAM_CHROMIUM_EXECUTABLE to a compatible browser. Keep Beam running while exporting an open project with HTML layers: it provides their rendered frames. Replace the ids below, and choose a frame time inside the video’s duration.

Screenshot uses its document’s PNG/WebP settings; match the output extension to that format. Video supports MP4 and WebM with the composition’s layers, captions and zooms. To intentionally replace an existing destination, pass 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"}'

Edit an image file without the desktop app

Start with an existing PNG and its actual dimensions. Save only the commands array from the Screenshot transaction as edits.json, then create, edit and export the standalone document below. This workflow changes a file document, not an open Beam editor.

Standalone edit and serve do not require the desktop app. Export needs the CLI Chromium backend. For an HTML video without an editor, use motion with a job file; beam-cli docs html describes the entry, dimensions, duration in seconds, fps and format.

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

Understand what runs locally

The CLI connects to the desktop through an authenticated local endpoint. Beam renders locally. Published HTML runs in sandboxed windows without Node access or a Beam preload; external network requests are blocked, so bundle its resources locally.

You supply the agent and model. Their data handling depends on the provider you choose. Beam supplies the document tools and rendering interface; it does not include an AI chat subscription, an MCP stdio server or shared network editing.