excalidraw scenes

Work with Excalidraw scenes, including metadata, collection placement, and drawing content.

excalidraw scenes [options] [command]

Examples

excalidraw scenes list --limit 25
excalidraw scenes list --collection-id <collectionId>
excalidraw scenes get <sceneId>
excalidraw scenes content get <sceneId> --out scene.json

Notes

• Scene metadata commands do not read or write drawing elements.
• Use excalidraw scenes content --help for commands that handle the canvas JSON.
• Every scene belongs to a collection. Personal (uk-) API keys may pass private as the collection ID.

renderCopy Anchor Link

Fetch scene content through the public API, then render it locally with an installed browser.

excalidraw scenes render [options] <sceneId>

Examples

excalidraw scenes render <sceneId> --out scene.png
excalidraw scenes render <sceneId> --out scene.svg --theme dark
excalidraw scenes render <sceneId> --frame-id <frameId> --out frame.png
excalidraw scenes render <sceneId> --all-frames --out slides/
excalidraw scenes render <sceneId> --out - > scene.png

Notes

• Needs an API key that can read the scene, and an installed Chrome, Chromium, Edge or Firefox. The key never reaches the browser.
• The format follows the --out extension, .png or .svg, unless --format is set. SVGs embed their fonts and have no size limit.
• --all-frames writes each frame to the --out directory as its own file, numbered in presentation order, such as 01-intro.png.
• With --out -, stdout gets only the image, without the JSON summary. Errors and retry notices go to stderr.
• Fonts, proxies, browsers and size limits: /docs/cli/rendering

listCopy Anchor Link

List scene metadata, sharing links, and collection assignments without fetching full canvas content.

excalidraw scenes list [options]

Examples

excalidraw scenes list --limit 50
excalidraw scenes list --collection-id <collectionId> --limit 25
excalidraw scenes list --all --output table

Notes

• Use this first when you need scene IDs for follow-up commands.
• Use --limit to keep output bounded for scripts and agents, or --all to walk every page.
• With --all the output is { count, data } instead of a single page with hasNextPage.

getCopy Anchor Link

Get one scene's metadata, sharing links, pinned state, and collection assignment.

excalidraw scenes get [options] <sceneId>

Examples

excalidraw scenes get <sceneId>

Notes

• This returns metadata only. Use scenes content get to fetch drawing elements and files.

createCopy Anchor Link

Create a scene in a collection. With --file, write its drawing content in the same run; without it, the scene starts empty.

excalidraw scenes create [options]

Examples

excalidraw scenes create --name "Architecture sketch" --collection-id <collectionId>
excalidraw scenes create --name "Sprint board" --collection-id <collectionId> --pinned
excalidraw scenes create --name "Scratchpad" --collection-id private
excalidraw scenes create --name "Imported" --collection-id <collectionId> --file drawing.excalidraw
generate-diagram | excalidraw scenes create --name "Generated" --collection-id <collectionId> --file -

Notes

• --file takes a full Excalidraw export or a partial payload with elements, appState or files, and is checked before the scene is created. Without it the scene starts empty.
• Workspace API keys need a real collection ID; personal (uk-) keys may pass private for the owner's private collection.
• More: /docs/cli/scene-content

updateCopy Anchor Link

Rename, pin, or move a scene without changing its drawing content.

excalidraw scenes update [options] <sceneId>

Examples

excalidraw scenes update <sceneId> --name "Updated diagram"
excalidraw scenes update <sceneId> --collection-id <collectionId>
excalidraw scenes update <sceneId> --no-pinned

Notes

• Provide at least one field to update. Omitted fields stay unchanged.
• Use --pinned to pin and --no-pinned to unpin.

deleteCopy Anchor Link

Soft-delete a scene by moving it to trash. This does not permanently destroy it.

excalidraw scenes delete [options] <sceneId>

Examples

excalidraw scenes delete <sceneId>

Notes

• Existing links or integrations may stop working while the scene is in trash.

shareCopy Anchor Link

Set what anyone with the scene's public link may do, and print the link. This is the link from the scene's Share dialog.

excalidraw scenes share [options] <sceneId>

Examples

excalidraw scenes share <sceneId> --access view
excalidraw scenes share <sceneId> --access edit
excalidraw scenes share <sceneId> --access none
excalidraw scenes share <sceneId> --access view | jq -r .url

Notes

• Anyone with the link can open the scene without signing in. With view or edit, they can also read and write comments.
• The output is the link's access and its URL; url is null once the link is off.
• Turning the link on fails with HTTP 403 when a workspace admin has disabled scene sharing.

share-slidesCopy Anchor Link

Turn the scene's shared presentation link on, or off with --off, and print the link. Anyone with the link can step through the scene's frames as slides without signing in.

excalidraw scenes share-slides [options] <sceneId>

Examples

excalidraw scenes share-slides <sceneId>
excalidraw scenes share-slides <sceneId> --off

Notes

• Each frame in the scene is one slide. Sharing fails with HTTP 400 when the scene has no frames.
• The link stays the same when sharing is turned off and on again; url is null while it's off.
• Turning sharing on fails with HTTP 403 when a workspace admin has disabled scene sharing.

contentCopy Anchor Link

Work with the complete Excalidraw scene content: elements, files, app state, and version data.

excalidraw scenes content [options] [command]

Examples

excalidraw scenes content get <sceneId> --out scene.json
excalidraw scenes content patch <sceneId> --file patch.json
excalidraw scenes content put <sceneId> --file replacement.json

Notes

• Prefer patch for incremental agent edits. Use put only for authoritative full replacements.
• Patch merges with the stored scene; put replaces the stored scene.

content getCopy Anchor Link

Return the full scene JSON, including elements, files, app state, and embedded file status.

excalidraw scenes content get [options] <sceneId>

Examples

excalidraw scenes content get <sceneId>
excalidraw scenes content get <sceneId> --out scene.json

Notes

• Large scenes can produce large JSON. Use --out when saving content for review, backup, or later patching.
• GET responses may include filesFailedToEmbed; write commands ignore that field if it is reused as input.

content putCopy Anchor Link

Authoritatively replace a scene with the complete Excalidraw content JSON from a file.

excalidraw scenes content put [options] <sceneId>

Examples

excalidraw scenes content put <sceneId> --file replacement.json
cat drawing.excalidraw | excalidraw scenes content put <sceneId> --file -

Notes

• This is a full replacement: elements not present in the file are removed from the scene.
• The file only needs elements; missing fields are filled in, and the file is checked before anything is sent.
• Connected editors are forced to reload. For most automated edits, use patch instead.
• More: /docs/cli/scene-content

content patchCopy Anchor Link

Patch scene content by merging the supplied elements, files, or appState fields into the current scene.

excalidraw scenes content patch [options] <sceneId>

Examples

excalidraw scenes content patch <sceneId> --file patch.json
echo '{"appState":{"viewBackgroundColor":"#f8f9fa"}}' | excalidraw scenes content patch <sceneId> --file -

Notes

• Send at least one of elements, appState or files. Elements and files you leave out are kept.
• Elements merge by ID, and the higher version wins: to change an element, send it with its version increased. Send it with isDeleted: true to remove it.
• Files are added or replaced by ID. From appState, only viewBackgroundColor and lockedMultiSelections are stored.
• More: /docs/cli/scene-content