Documentation Index
Fetch the complete documentation index at: https://mintlify.com/GraphiteEditor/Graphite/llms.txt
Use this file to discover all available pages before exploring further.
graphene-cli is a command-line tool for compiling and exporting Graphite documents programmatically. It loads a .graphite or .gdd document file, compiles the node network using the same Graphene engine that runs inside the editor, and renders the result to a file — all without opening a browser or the Graphite GUI. This makes it well-suited for batch processing, CI/CD pipelines, automated screenshot generation, and headless rendering workflows.
Commands
graphene-cli provides the following subcommands:
| Command | Purpose |
|---|
compile | Compile a document’s node network and optionally print the resulting proto-network |
export | Compile and render a document, writing output to SVG, PNG, JPG, or GIF |
list-node-identifiers | Print all registered node identifiers known to the engine |
compile
graphene-cli compile [OPTIONS] <document>
Options
| Flag | Short | Description |
|---|
--print-proto | -p | Print the compiled proto-network to stdout |
--verbose | -v | Increase log verbosity (repeat for more: -v = info, -vv = debug, -vvv = trace) |
Example
# Compile and print the proto-network for inspection
graphene-cli compile --print-proto my-artwork.graphite
export
graphene-cli export <document> -o <output> [OPTIONS]
--output determines the export format automatically.
Arguments
| Argument | Required | Description |
|---|
<document> | ✓ | Path to the .graphite or .gdd document file |
Options
| Flag | Short | Type | Default | Description |
|---|
--output <path> | -o | path | — | Output file path; extension sets the format (.svg, .png, .jpg, .gif) |
--scale <f64> | | float | 1.0 | Scale factor applied to the canvas dimensions |
--width <u32> | | integer | — | Override output width in pixels |
--height <u32> | | integer | — | Override output height in pixels |
--transparent | | flag | false | Preserve alpha channel (PNG only; ignored for JPG and SVG) |
--fps <f64> | | float | 30 | Frames per second for animated GIF export |
--frames <u32> | | integer | — | Total number of frames to render for GIF export |
--duration <f64> | | float | — | Animation duration in seconds for GIF (takes precedence over --frames) |
--verbose | -v | flag | — | Increase log verbosity (repeatable) |
When both --duration and --frames are provided, --duration takes precedence and --frames is ignored. If neither is specified for a GIF export, only a single frame is rendered.
Examples
# Export to SVG (vector, lossless)
graphene-cli export logo.graphite -o logo.svg
# Export to PNG at 2× scale
graphene-cli export artwork.graphite -o artwork.png --scale 2
# Export to PNG with transparency preserved
graphene-cli export artwork.graphite -o artwork.png --transparent
# Export to PNG at a fixed resolution
graphene-cli export artwork.graphite -o thumb.png --width 800 --height 600
# Export a 3-second animated GIF at 24 fps
graphene-cli export animation.graphite -o animation.gif --fps 24 --duration 3.0
# Export an animated GIF with an explicit frame count
graphene-cli export animation.graphite -o animation.gif --fps 30 --frames 90
Supported Output Formats
| Format | Extension | Notes |
|---|
| SVG | .svg | Vector output, fully scalable; rendered directly from the node graph |
| PNG | .png | Raster output; use --transparent to preserve the alpha channel |
| JPG | .jpg or .jpeg | Raster output; no transparency support; good for photographs |
| GIF | .gif | Animated raster output; use --fps and --duration or --frames to control the animation |
graphene-cli returns an error listing the supported options.
Document Formats
graphene-cli supports two document formats:
.graphite — The legacy JSON-based document format. Loaded directly by reading the file as a string..gdd — The newer archive format introduced in Graphite Alpha. Contains the node network along with embedded resources (images, fonts). Use extract-legacy-doc to extract a .graphite file from a .gdd archive.
# Extract the legacy .graphite document embedded in a .gdd file
graphene-cli extract-legacy-doc my-artwork.gdd
# Writes: my-artwork.graphite
Building from Source
graphene-cli is part of the Graphite workspace and can be built with Cargo:
# Build in release mode (recommended for performance)
cargo build -p graphene-cli --release
# Run the compiled binary
./target/release/graphene-cli export my-art.graphite -o output.png --scale 2
Use -v or -vv flags when troubleshooting export issues. The verbose output shows GPU initialization, node graph compilation steps, and per-frame rendering progress for animated GIFs.
graphene-cli uses internally, see Graphene Engine.