Skip to content

The command line tool

buhayin-cli: check, render, export, run a script and import from a terminal.

buhayin-cli works on scene files from a terminal, with no window. It uses the same code the editor does, so a frame it renders or a movie it exports comes out as it does from the editor. Use it to render and export many scenes in one go, to check scenes for problems, and to run a script over a folder of them.

It is inside the app, at Buhayin.app/Contents/MacOS/buhayin-cli. With Buhayin in Applications that is:

/Applications/Buhayin.app/Contents/MacOS/buhayin-cli

To run it by its name from any folder, link it onto your PATH once, or add the folder to your PATH in ~/.zshrc:

sudo ln -s /Applications/Buhayin.app/Contents/MacOS/buhayin-cli /usr/local/bin/buhayin-cli
export PATH="$PATH:/Applications/Buhayin.app/Contents/MacOS"

Use one of the two. The commands below are written as buhayin-cli, which assumes it is on your PATH.

buhayin-cli <command> [options] <scene files>
buhayin-cli <command> --help

A scene file ends in .bhy. --help lists the options of any command. A file it cannot open is refused in plain words: it does not exist, is a folder, is empty, is not text or not a scene.

The commands

CommandWhat it does
infoPrints a scene's name, length, frame rate, size, layers and render targets.
checkRuns the editor's scene check.
renderRenders one frame to a PNG.
exportExports frames, movies, sprite sheets and storyboard PDFs.
edit-listWrites a storyboard's shots as an edit list.
xsheetWrites the scene's Xsheet as a PDF.
scriptRuns a script on scene files.
import-vectorBrings an SVG, PDF or AI file into a scene.
import-harmonyConverts a Harmony scene folder into a scene file.
production, playback, cacheTools for timing the editor, described at the end.

info

buhayin-cli info scene.bhy

Prints the scene's name, length, frame rate, size, layers and render targets. A storyboard whose dissolves share frames also says how many frames play, such as 18 frames, 14 played.

check

buhayin-cli check scene.bhy
buhayin-cli check --fix scene.bhy

The same check as Scene > Check Scene…. Problems that change the picture come first, then notes that may be meant. A file it cannot read is reported and passed over.

FlagWhat it does
--fixPuts right what can be put right in one step. It writes each file back first, and says what it fixed and every file and folder it wrote.

The exit status is 1 while any file has problems, and 2 at the end when a file could not be read.

render

buhayin-cli render scene.bhy --frame 12 --size half --out frame12.png

Renders one frame as the finished shot: white paper, through the camera, straight at the size.

FlagWhat it does
--frame NThe frame, from 1. Frame 0 is refused.
--sizefull, threeQuarters, twoThirds, half, third or quarter of the scene's size. Anything else is full.
--draftTaken and ignored. Every frame is painted at its size either way.
--out file.pngWhere to write it. By default <title>-<frame>.png in the current folder.

It also takes the four render script flags below. Anything a frame leaves undrawn is named on standard error.

export

buhayin-cli export scene.bhy --format mp4 --frames 1-48 --out scene.mp4
buhayin-cli export --targets project-folder --out renders.zip

Exports as File > Export… does, into a zip, a folder, or a movie file. It takes scene files, or with --targets scene files or project folders.

FlagWhat it sets
--formatpng (the default), jpeg, psd (layered, one file a frame), tiff, exr (8 bit pictures written as half floats), sheet (a sprite sheet and its JSON), skeleton (an image for each attachment, with its data and a README), gif, mp4 (H.264), webm (VP9) or mov (ProRes).
--codecFor a MOV: prores422proxy, prores422lt, prores422, prores422hq (the default) or prores4444, which keeps the alpha of --transparent.
--from, --to, --framesThe first and last frame. --frames 1-24 sets both and wins over the other two. A first frame after the last, or outside the scene, is refused with exit 2. A last frame past the scene's is held to it, with a line saying so.
--size, --draftThe size, as for render.
--transparentLeaves the paper out, for a PNG, PSD, sheet or a MOV in ProRes 4444.
--separationline, colour or matte in place of the whole picture, for any format but a skeleton.
--layersOnly these layers, named and split by commas, anywhere in the scene's tree.
--ditherA GIF's dithering: none, diffusion, pattern or noise.
--no-loopA GIF that plays once.
--sheetA sprite sheet's layout: grid (the default), easel, paper2d or xml.
--trim, --drop-empty, --drop-duplicatesWhat a packed sheet cuts down, leaves out or draws once.
--sheet-width, --sheet-heightThe widest and tallest a packed sheet may be, 128 to 16384 pixels, 8192 by default.
--jpeg-qualityA JPEG's quality in percent, 50 to 100, 92 by default. Another value is refused.
--targetRenders the scene's render target of that name, as it is set up.
--targetsA batch render: every render target each scene keeps, or every scene of a project folder, into one zip or folder. Targets turned off are passed over.
--pdf, --profileThe storyboard's boards as a PDF, laid out by a profile that ships with Buhayin or one the board keeps.
--outA .zip, a folder, the movie's own file, or the PDF. By default <name>.zip, <name>.mp4 (or .webm, .mov) or <name>.pdf in the current folder.

A storyboard's frames are numbered as it plays, and the last line counts the frames written, such as Frames 1 to 18, the 14 that play. A movie format this build cannot write is refused with the reason, or left out of a batch.

The render script flags

render and export can run a script round a render.

FlagWhat it does
--pre-render-script file.jsRuns a script file on each scene as it is read.
--pre-render-inline-script "code"The same, with the code on the command line.
--post-render-script file.jsRuns a script file on each scene after its render is written.
--post-render-inline-script "code"The same, with the code on the command line.

The edits of a pre render script show in the render and are never written to the file. A post render script sees hook.output. A script that fails stops the command with exit 2.

edit-list

buhayin-cli edit-list board.bhy --format otio --out board.otio

Writes a storyboard's shots as an edit list for a video editor.

FlagWhat it does
--formatedl (CMX 3600), otio, xml or aaf.
--outWhere to write it.

xsheet

buhayin-cli xsheet scene.bhy --pdf xsheet.pdf

Writes the scene's Xsheet as a PDF, laid out in the pages the Xsheet prints, with hidden columns left out. --pdf is required, and --out means the same.

script

buhayin-cli script cleanup.js a.bhy b.bhy --out cleaned

Runs a script on scenes as the Script view runs it, each scene in a sandbox of its own, stopped at 10 seconds. The script comes first, then the scene files.

FlagWhat it does
--outWhere the changed scene goes. For several scenes it is a folder.
--frame NThe frame the script starts on, 1 by default. A frame outside the scene is refused with exit 2.
--layer nameThe current layer for the script. A layer the scene does not have is refused with exit 2.

The script sees buhayin, print and console. It also sees hook, with hook.event set to batch. The scene's pictures are loaded first, so the script can paint a canvas it has, and with --out the canvases it painted are written beside the scene it leaves. A script file exported from the Script view loses its first line, the name.

There is no window, so calls that need the editor throw NO_EDITOR, and buhayin.ask throws NO_WINDOW.

import-vector

buhayin-cli import-vector --scene scene.bhy --out with-art.bhy art.svg

Brings an SVG, PDF or AI file into a scene file. Each page becomes a drawing on a frame of one drawing layer, with its fills, pencil lines and their colours in the palette. Nothing in the file is fetched from anywhere else. What the file held that is not read is listed in the answer.

FlagWhat it does
--scene, --outThe scene to add to, and where to write the result. Both are required.
--layerThe layer to draw on.
--frameThe first frame to put a page on.
--first-page, --last-pageWhich pages of a PDF to bring in.

import-harmony

buhayin-cli import-harmony scene-folder --out imported.bhy

Converts a Harmony scene folder into a scene file and its assets. A file of several scenes makes a scene file for each, the others named for their scenes beside the first. What has no place in Buhayin is named on standard error. A file already at --out is refused. The Harmony files are only read.

FlagWhat it does
--outWhere to write the scene file.

Tools for timing the editor

  • production <folder> writes a large scene into the folder to time the editor against, with its pictures and sound in assets. --layers sets how big, 987 by default.
  • playback times frames painted as the player paints them ahead. --frames, --size, --threads, --card, --layers, --preview, --auto and --compare FOLDER choose how, with --max-mean, --max-over-8 and --max-over-32 as limits for --compare.
  • cache reads the file of finished frames beside a scene, and --clear empties it first.

Exit status

StatusMeaning
0It worked.
1check found problems, or playback --compare went past a limit.
2A bad argument, such as a frame outside the scene, a file it could not read, or a render script that failed.