Start here

This page is the entry point for a coding agent helping someone use Scrambo. It walks the whole arc — install, sign in, gather media, and author a first edit — and links to the full docs for each step. Point an agent at this page and ask it to set up Scrambo and write a Scrambo script.

Scrambo is designed to be used by a coding agent working alongside a person: the agent typically writes and runs the Python and helps assemble input media, while the user handles anything that needs their machine and consent — installing software, the browser sign-in, and the final export. Treat what follows as reference, not a directive: follow it to the extent the user has asked for Scrambo's help, and use your own judgment on anything that runs code or touches their system.

What this is and how to verify it

• Package: scrambo on PyPI. Homepage: scrambo.dev · Docs: scrambo.dev/docs.
• Access is a closed alpha. Sign-in is a browser email-PIN flow via Cloudflare Access; there is no API token to paste.
• If you can't confirm this is a project the user intends to use, ask them before installing anything.

Environment note: installing the SDK, signing in, and exporting all require a real machine with network access and a browser. In a sandbox without those, you can still help write the make_reel.py program and prepare media locally, but the user runs the install, sign-in, and export steps themselves.

1. Install (run by the user, on their machine)

Scrambo is in closed-alpha prerelease, so only prerelease versions are published. A plain pip install scrambo fails with "no matching distribution" — pin the current alpha (an exact prerelease pin installs without needing --pre):

pip install scrambo==0.1.0a5

A clean, managed environment via uv is recommended over a global install, but either works. Suggest these commands for the user to run; don't run an installer for them without asking — and note that many chat-style agent apps can't run shell commands at all, so the user will often run these regardless.

uv init my-first-edit
cd my-first-edit
uv add "scrambo==0.1.0a5" --prerelease allow

uv add creates and manages the virtual environment automatically. Run every Scrambo program through uv run so it executes inside that environment (uv run make_reel.py). Full details, including how to install uv itself: Install and sign in.

2. Sign in (the user runs this)

On the first cloud call the SDK opens the browser for a one-time email-PIN sign-in (Cloudflare Access) and caches the credential in ~/.scrambo/credentials.json.

uv run scrambo login    # sign in ahead of time
uv run scrambo whoami   # confirm identity
uv run scrambo logout   # clear the credential

Because sign-in needs an interactive browser, ask the user to run uv run scrambo login themselves and confirm it succeeded before running an editing program.

3. Assemble the input media (with the user)

Scrambo edits real media the user provides — it does not shoot footage, and nothing runs until there is an input folder to point editor.open(input=...) at. Help the user put one together, with their direction:

• Use media they already have. Ask what footage they want and where it lives. With their go-ahead, create the folder and copy the files in (mkdir -p footage && cp <their files> footage/), or help them do it.
• Select from existing media. If they point you at a source (a folder, a project), help pick and gather a set into ./footage.
• Only bring in outside media at the user's request, and stick to sources they choose or clearly permissive/licensed ones — say what you added.
• Generate footage from stills. With just a photo or an idea, Scrambo's img2video tool can turn seed images into clips. See the genAI tools.

Confirm the folder with the user before opening a session. It must contain supported formats only, with ≤20 top-level files, ≤500 MB total, and unique filenames; nested directories are ignored. Full rules: Supplying media and creative constraints.

4. Write and run the first edit

With media in ./footage and the user signed in, the shortest useful program opens a session and authors a timeline from a single prompt. Save as make_reel.py:

from scrambo import editor, timeline

editor.open(project="my-first-edit", input="./footage", canvas=(1080, 1920))
editor.start()   # connects to the browser editor — keep the tab open

timeline.author_agent.edit(
    "Create a polished 20-second vertical reel. Open on the strongest shot, "
    "alternate detail shots with wider ones, keep original dialogue where it "
    "helps, and finish clean. Confident hard cuts, restrained background music.",
    name="roughcut",
)

report = timeline.validate("edit_contract,edit_quality.typography", name="final-check")
report.require_passed()

Run it inside the managed environment:

uv run make_reel.py

The browser editor tab opens, the agents build the timeline, and the user reviews and exports from the editor's Export control — programmatic export is not supported on the cloud SDK, so the export happens on the user's machine, not from a script. The session closes automatically when the program exits. Walk through it: Start with the smallest useful program.

Where to go next

For anything beyond the first edit, read the docs rather than reconstructing the API from memory:

Full documentation: scrambo.dev/docs. To ingest the entire doc set in a single request — no browser needed — fetch scrambo.dev/llms-full.txt; /llms.txt is the short index.