CoA CLI

coa renders CoAnimator projects to MP4 without opening an editor window. This reference covers CoAnimator 0.7.2. The CLI shares the app's capture, composition and output validation. Encoded files can differ across engines, hardware and platforms; byte-identical output is not guaranteed.

Putting coa on your PATH

Open Settings → General → Command line & agent skill → Install coa command. The native CoAnimator → Install coa Command Line Tool… menu also opens the installer.

Open a new terminal and run coa --help. Restart already-open terminal applications if they have not picked up the PATH change.

The app supplies the CLI runtime: no separate Node.js/npm installation is needed. FFmpeg and FFprobe are required for rendering. Use media setup or provide them on PATH; FFMPEG_PATH and FFPROBE_PATH can specify their locations. The agent skill is optional guidance and does not install the command.

Rendering

# defaults: resolution follows the licence, FPS follows the timeline
coa render my-demo

# set resolution, frame rate and compression separately
coa render my-demo --resolution 1080p --fps 24 --quality high

# render a section of a named timeline
coa render my-demo --timeline shorts --start 1 --end 5 --workers auto

# a packaged project works too
coa render launch-video.coa --out launch.mp4

The target can be a project ID, a folder containing project.json, or a .coa file. Higher resolutions require an eligible licence; Free exports use a 720p short side and a watermark.

Auto estimates workers from system capacity. More workers need more memory and are not always faster. Output names distinguish explicit timelines, nonstandard quality and ranges; use --out for a fixed filename.

Packing and unpacking

coa pack my-demo --out launch-video.coa
coa unpack launch-video.coa --out ./launch-video

pack creates a shareable .coa without converting the source into a package-backed project. Duplicate linked projects into CoAnimator before packing. unpack extracts to an empty folder; it does not import into the app. See Projects.

Rendering a .coa uses its bound working copy when the package file has not changed, including unsaved working-copy edits. Otherwise it extracts temporarily, renders beside the package and removes the temporary files.

Validation, cancellation and failures

The CLI checks dimensions, frame count, FPS, duration and expected audio before replacing the destination. A recoverable failure retries once with Standard, one worker and software encoding. Failed or cancelled exports preserve an existing destination.

Ctrl+C cancels and cleans up the active render without retrying. Forcibly killing the process cannot perform cleanup. Exit code 0 means success and 1 means failure. Set DEBUG=1 for a fuller error trace.

For timeline errors, open the project and use Timeline Health to review safe repairs or relink media. For a missing command, reinstall from Settings and open a fresh terminal. The CLI uses the cached licence; open the app to activate or refresh it.

Updates and skills

Packaged app launches repair managed Windows launchers after the application moves, and AppImage wrappers after an update changes the filename. Custom or deleted commands are preserved. Reinstall from Settings if a protected location cannot be repaired.

Managed, unchanged skills also refresh on packaged app launch. Start a new agent session after the update. See Skills.

Headless Linux and CI

Electron still needs a display server on a headless machine:

xvfb-run -a coa render my-demo --preset 720p30
# or invoke an AppImage directly (replace the filename with your installed version)
xvfb-run -a ./CoAnimator-0.7.2.AppImage --cli render my-demo

Install CoAnimator, FFmpeg/FFprobe and the display-server dependencies on the runner. The CLI works in scripts and schedulers, but 0.7.2 does not provide hosted rendering workers. Project rendering produces MP4; standalone tools support additional formats.