Command line tool

Screencake from the command line.

Read and write scripts, call sheets, storyboards, beats, crew, and cast from a terminal. The same tool serves a person and an agent.

What the tool does Link to What the tool does#

screencake is one binary that signs in to your account and works on your scripts. On a terminal, it shows tables, spinners, and the script text. When you pipe its output, or give --json, it prints one JSON value and nothing else.

Reads use HTTP. Writes to script content and production data use the same collaboration connection as the app, so roles, plans, and authorship apply to the tool.

Install Link to Install#

From the desktop app Link to From the desktop app#

  1. Open the Account menu in the desktop app.
  2. Select Install command line tool.

The app puts screencake on your PATH and signs the tool in. The tool uses its own device session. The account page shows it as Command line. To stop the tool, revoke that session on the account page.

With Homebrew Link to With Homebrew# 

brew tap screencake/tap && brew install screencake

After the installation, sign in with screencake auth login.

Sign in Link to Sign in# 

screencake auth login

The command opens the browser at the sign-in confirmation page and waits on a local port. When you confirm, the browser sends the tool a short-lived token. The tool exchanges it for a device session and saves the credentials. Use --no-browser to print the URL instead.

screencake auth status shows who is signed in and the server in use. screencake auth logout revokes the session and deletes the stored credentials.

Use HTTPS for remote servers. HTTP is available only for loopback development servers. A CLI session created by the desktop app keeps the original sign-in deadline. Installing the tool does not extend a workspace session-age limit.

Environment variables replace the stored credentials and control the output:

  • SCREENCAKE_TOKEN — A device session token. It replaces the stored credentials for one command.
  • SCREENCAKE_URL — The server origin. The default is the signed-in server, then https://screencake.com.
  • SCREENCAKE_CONFIG_DIR — The directory that holds credentials.json.
  • SCREENCAKE_NO_ANIMATION — Set to 1 to stop spinners and other motion on a terminal.
  • NO_COLOR — Set to remove color from terminal output.

Workspaces and projects Link to Workspaces and projects#

screencake workspaces list lists your workspaces. screencake projects list lists projects, or the projects of one --workspace. screencake projects create --workspace ID --title TITLE creates a project. screencake projects rename ID --title TITLE renames one.

Scripts Link to Scripts#

Script commands take the script ID from scripts list. The tool refuses content commands on an encrypted script with the error code encrypted_script, because it cannot decrypt the content.

scripts list Link to scripts list#

List scripts, or the scripts of one project.

screencake scripts list --project 01J8…

scripts show Link to scripts show#

Show one script record.

screencake scripts show 01J8…

scripts create Link to scripts create#

Create a script. --from reads a Fountain file, or stdin with -.

screencake scripts create --project 01J8… --title "Night Bus" --from draft.fountain

scripts read Link to scripts read#

Print the script text as Fountain.

screencake scripts read 01J8…

scripts write Link to scripts write#

Replace the script text from a Fountain, FDX, or text file. Use - for stdin.

screencake scripts write 01J8… draft.fountain

scripts export Link to scripts export#

Export the script as fountain, fdx, pdf, or docx.

screencake scripts export 01J8… --format pdf --out night-bus.pdf

scripts versions Link to scripts versions#

List the named versions.

screencake scripts versions 01J8…

scripts save-version Link to scripts save-version#

Save a named version.

screencake scripts save-version 01J8… --label "Table read draft"

scripts restore Link to scripts restore#

Restore a named version as the current text.

screencake scripts restore 01J8… 01J9…

scripts rename Link to scripts rename#

Rename a script.

screencake scripts rename 01J8… --title "Night Bus (blue)"

scripts archive Link to scripts archive#

Archive a script.

screencake scripts archive 01J8…

Call sheets Link to Call sheets#

Call sheet commands work on the shoot days of one script. Day, event, and member IDs come from callsheet days and crew list.

callsheet days Link to callsheet days#

List shoot days with their assigned scenes.

screencake callsheet days 01J8…

callsheet add-day Link to callsheet add-day#

Add a shoot day. --fields takes other day fields as JSON.

screencake callsheet add-day 01J8… --title "Day 1" --date 2026-10-19 --location "Bus depot"

callsheet update-day Link to callsheet update-day#

Change a shoot day. FIELDS is JSON, @file, or -.

screencake callsheet update-day 01J8… 01JD… '{"parking":"Lot B"}'

callsheet remove-day Link to callsheet remove-day#

Remove a shoot day and its assignments.

screencake callsheet remove-day 01J8… 01JD…

callsheet assign Link to callsheet assign#

Assign a scene to a day. SCENE is the scene uid or its number.

screencake callsheet assign 01J8… --day 01JD… --scene 3

callsheet unassign Link to callsheet unassign#

Remove a scene from its day.

screencake callsheet unassign 01J8… --scene 3

callsheet add-event Link to callsheet add-event#

Add a day event, for example a call or a meal.

screencake callsheet add-event 01J8… --day 01JD… --label "Crew call" --start 2026-10-19T13:00:00Z

callsheet remove-event Link to callsheet remove-event#

Remove a day event.

screencake callsheet remove-event 01J8… 01JE…

callsheet show Link to callsheet show#

Print the assembled call sheet for one day as JSON.

screencake callsheet show 01J8… 01JD…

callsheet pdf Link to callsheet pdf#

Write the call sheet PDF to --out or stdout.

screencake callsheet pdf 01J8… 01JD… --out day-1.pdf

callsheet distribute Link to callsheet distribute#

Email the call sheet to the crew, or to the given --member IDs.

screencake callsheet distribute 01J8… 01JD… --member 01JM…

Storyboard Link to Storyboard#

A frame belongs to a shot. Find the shot uid with doc dump or scripts read.

storyboard list Link to storyboard list#

List frames in strip order.

screencake storyboard list 01J8…

storyboard add Link to storyboard add#

Add a frame for a shot. --image uploads a JPEG or PNG.

screencake storyboard add 01J8… --shot 01JS… --caption "Close on the lid" --image frame.jpg

storyboard update Link to storyboard update#

Change a frame. FIELDS is JSON, @file, or -.

screencake storyboard update 01J8… 01JF… '{"holdMs":1500}'

storyboard upload Link to storyboard upload#

Replace the picture of a frame.

screencake storyboard upload 01J8… 01JF… frame.png

storyboard remove Link to storyboard remove#

Remove a frame.

screencake storyboard remove 01J8… 01JF…

Beats, crew, cast Link to Beats, crew, cast#

beats list Link to beats list#

List beats in board order.

screencake beats list 01J8…

beats add Link to beats add#

Add a beat. --after places it after a beat key.

screencake beats add 01J8… --title "Inciting incident" --lane A --scene 3

beats update Link to beats update#

Change a beat. FIELDS is JSON, @file, or -.

screencake beats update 01J8… t:0123456789abcdef '{"color":"red"}'

beats remove Link to beats remove#

Remove a beat.

screencake beats remove 01J8… t:0123456789abcdef

crew list Link to crew list#

List crew members.

screencake crew list 01J8…

crew add Link to crew add#

Add a crew member. --fields takes callOffsetMin, dayRateCents, and currency as JSON.

screencake crew add 01J8… --name "Ola Grip" --department Camera --position "1st AC"

crew update Link to crew update#

Change a member. FIELDS is JSON, @file, or -.

screencake crew update 01J8… 01JM… '{"phone":"+1 555 0100"}'

crew remove Link to crew remove#

Remove a member.

screencake crew remove 01J8… 01JM…

crew call Link to crew call#

Set the call time of a member on a day.

screencake crew call 01J8… --day 01JD… --member 01JM… --at 2026-10-19T12:30:00Z

cast list Link to cast list#

List cast entries.

screencake cast list 01J8…

cast set Link to cast set#

Cast a character. --actor takes the actor fields as JSON.

screencake cast set 01J8… --character DEV --actor '{"name":"Dev Patel","agency":"UTA"}'

cast remove Link to cast remove#

Remove the cast entry of a character.

screencake cast remove 01J8… --character DEV

Raw maps Link to Raw maps#

Each script document holds named maps of production data. The doc commands read and write their entries directly. An entry is the same JSON object that the app writes, so the app shows your change at once.

The map names are:

animatic  authors  availability  beats  breakdown  budget  cast  characters  comments  coverage  crew  locations  moodboard  scenePlan  schedule  storyboard  sustainability  tasks  threads  travel

doc get Link to doc get#

Print every entry of one map as a JSON object, or one entry with --key.

screencake doc get 01J8… schedule --key d:01JD…

doc set Link to doc set#

Insert or replace one entry. VALUE is JSON, @file, or -.

screencake doc set 01J8… crew m:01JM… @member.json

doc delete Link to doc delete#

Remove one entry.

screencake doc delete 01J8… crew m:01JM…

doc apply Link to doc apply#

Apply a JSON array of {"map","key","value"} operations. A null value removes the entry.

screencake doc apply 01J8… @ops.json

doc dump Link to doc dump#

Print every map of the script, and the screenplay as ProseMirror JSON.

screencake doc dump 01J8…

For agents Link to For agents#

When stdout is not a terminal, the tool prints one JSON value and no other text. --json gives the same output on a terminal. --pretty indents the value. --compact prints it on one line.

On failure, the tool prints one JSON object on stderr and exits with a nonzero code: 

{"error":"encrypted_script","message":"…"}
  • 0 — The command completed.
  • 1 error — A network, file, or server failure.
  • 2 usage — Invalid arguments or invalid JSON input.
  • 3 unauthorized — No credentials, or the server answered 401. Run screencake auth login.
  • 4 not_found — The server answered 404, or no record has the given ID.
  • 5 refused — The server refused the operation. The error code names the cause, for example plan_required, forbidden, or encrypted_script.

Set NO_COLOR to remove color and SCREENCAKE_NO_ANIMATION=1 to stop motion. screencake completions SHELL prints a completion script for bash, zsh, fish, or PowerShell.

A prompt for your agent Link to A prompt for your agent#

Paste this text into the instructions of your AI agent. It tells the agent how to read results, which commands change data, and when to ask you first. screencake prompt prints the same text. 

# Working with Screencake from the command line

You have the `screencake` command line tool. It drives a Screencake workspace: scripts (screenplays), call sheets, storyboards, beats, crew, cast, and the raw production data behind them. Use it instead of the web app whenever a task touches a Screencake script.

## Ground rules

- Every command prints exactly one JSON value on stdout when its output is piped, which it is when you run it. Parse that. Never scrape prose.
- On failure the command prints one JSON object on stderr, `{"error": "<code>", "message": "…"}`, and exits non-zero: 1 failure, 2 usage, 3 not signed in, 4 not found, 5 refused by the server (the `error` code names the cause: `plan_required`, `forbidden`, `encrypted_script`, `not_projected`, …). Read the code, then fix the cause; do not retry blindly.
- IDs are 26-character public IDs from `list` commands or app URLs. Scripts are addressed by their ID alone; the tool resolves the workspace and project itself.
- Writes are live. Each write command opens a collaboration session on the script, applies the change, waits until the server has stored it, and exits. There is no draft state and no undo except `scripts restore`. Confirm with the user before a destructive command: `scripts write` (replaces the whole text), `scripts archive`, every `remove`/`delete`, `callsheet distribute` (sends email).
- Prefer the typed commands (`scripts`, `callsheet`, `storyboard`, `beats`, `crew`, `cast`). Use `doc` only for data the typed commands do not cover.
- Encrypted scripts refuse every content and data command with `encrypted_script`. Tell the user; there is no workaround.
- Do not pass `--token` on the command line where it would be logged. Credentials are already stored; if `auth status` exits 3, ask the user to run `screencake auth login` in their terminal (it opens a browser).

## Start every task

```
screencake auth status
screencake scripts list
```

`scripts list` returns `[{id, title, kind, page_format, project_id, updated_at, …}]`. When several scripts could match the user's words, show the candidates and ask.

## Script text

```
screencake scripts read <ID>                      # Fountain text on stdout
screencake scripts export <ID> --format pdf --out script.pdf    # fountain | fdx | pdf | docx
screencake scripts write <ID> draft.fountain      # replaces the WHOLE text; also fdx or txt
screencake scripts write <ID> - < draft.fountain  # same, from stdin
screencake scripts create --project <PROJECT_ID> --title "…" --from draft.fountain
screencake scripts save-version <ID> --label "Before rewrite"
screencake scripts versions <ID>
screencake scripts restore <ID> <VERSION_ID>
```

To edit a script: `read` it, change the Fountain text, `save-version` first, then `write` the full text back. Keep every line you did not intend to change byte for byte. Write Fountain the standard way: scene headings in caps starting with `INT.`/`EXT.`, a character cue in caps on its own line, parentheticals in parentheses, transitions ending in `TO:`. A title page is `Key: Value` lines at the top followed by a blank line.

## Call sheets

```
screencake callsheet days <ID>
screencake callsheet add-day <ID> --title "Day 1" --date 2026-10-19 --location "Bus depot" \
  --fields '{"parking":"Lot B","hospital":"St. Luke’s","notes":"…"}'
screencake callsheet assign <ID> --day <DAY_ID> --scene 3          # scene number or uid; --after <scene> to order
screencake callsheet unassign <ID> --scene 3
screencake callsheet add-event <ID> --day <DAY_ID> --label "Crew call" --start 2026-10-19T07:00:00Z
screencake callsheet update-day <ID> <DAY_ID> '{"weather":"Rain, 58°F"}'
screencake callsheet show <ID> <DAY_ID>                            # day + scenes + events + crew calls + cast
screencake callsheet pdf <ID> <DAY_ID> --out day1.pdf
screencake callsheet distribute <ID> <DAY_ID> [--member <CREW_ID> …] [--tz America/Los_Angeles]
```

`distribute` emails real people. Ask first and report the `deliveries` and `skipped` arrays it returns.

## Crew and cast

```
screencake crew list <ID>
screencake crew add <ID> --name "Rhea Kapoor" --department electric --position Gaffer [--email …] [--phone …]
screencake crew call <ID> --day <DAY_ID> --member <CREW_ID> --at 2026-10-19T06:30:00Z [--note "…"]
screencake crew update <ID> <CREW_ID> '{"position":"Best boy"}'
screencake cast list <ID>
screencake cast set <ID> --character "DEV" --actor '{"name":"Ana Ruiz","agency":"…","agentName":"…"}'
```

Departments: production, direction, camera, grip, electric, sound, art, wardrobe, makeup, locations, transport, post, other. Character names are matched by their cue in the script (`DEV (V.O.)` and `DEV` are the same character).

## Storyboard and beats

```
screencake storyboard list <ID>
screencake storyboard add <ID> --shot <SHOT_UID> --caption "Close on the lid" --hold-ms 1500 --image frame.jpg
screencake storyboard upload <ID> <FRAME_ID> frame.jpg
screencake beats list <ID>
screencake beats add <ID> --title "Dev brings the cake" --lane act-1 --scene 1 [--after <BEAT_KEY>]
```

Shot uids come from `doc dump` (`screenplay` nodes of type `shot`, attribute `uid`); scene uids and numbers from its `scenes` array. Frame pictures must be JPEG.

## Raw data (`doc`)

```
screencake doc dump <ID>                # every map + screenplay as ProseMirror JSON + scenes index
screencake doc get <ID> schedule        # one map; --key <KEY> for one entry
screencake doc set <ID> schedule x:<ULID> '{"title":"Camera test","kind":"prep","date":"2026-10-15"}'
screencake doc delete <ID> tasks k:<ID>
screencake doc apply <ID> '[{"map":"tasks","key":"k:…","value":{…}},{"map":"tasks","key":"k:…","value":null}]'
```

Maps: animatic, authors, availability, beats, breakdown, budget, cast, characters, comments, coverage, crew, locations, moodboard, scenePlan, schedule, storyboard, sustainability, tasks, threads, travel. Entries are the same JSON the app writes; copy an existing entry's shape from `doc get` before inventing one. The tool stamps authorship for you.

## Reporting back

After a write, re-read what you changed (`callsheet show`, `beats list`, `scripts read`) and quote the result. Give the user the script ID and, for call sheets, the day ID. Mention anything the server refused and why.