Chapter 11
AI assistants and the command line
Use graphicseditor-cli to let an AI assistant draw in Graphics Editor, or to build, change and export documents from scripts.
What graphicseditor-cli is
graphicseditor-cli is Graphics Editor without its window. It uses the same document model, renderer and file formats as the app, so an AI assistant or a script can create and edit artwork directly. What it saves is an ordinary Graphics Editor document: you open the .mgfx file in the app and everything in it is editable.
It is installed with Graphics Editor. The installer puts the folder <install>\cli on your PATH, where <install> is the folder you installed Graphics Editor into (by default C:\Program Files\Motaware\Graphics Editor). Open a new terminal after installing, so that it sees the new PATH, and type:
graphicseditor-cli --help
This prints every command and option, and ends with the exact line for adding it to Claude Code on your computer. graphicseditor-cli --version prints the version.
What you need
graphicseditor-cli needs a Motaware plan that includes the desktop apps, or a permanent license for this major version of Graphics Editor. These are the same plans that let you create and save in the app.
Signing in
graphicseditor-cli keeps its own sign-in, separate from the app's. Signing in to the app does not sign in the command line, and signing out of one does not sign out the other.
| Command | What it does |
|---|---|
graphicseditor-cli login |
Opens your web browser so you can sign in to your Motaware account. |
graphicseditor-cli login --no-browser |
Prints the sign-in address instead of opening the browser. Open it yourself on the same computer. |
graphicseditor-cli logout |
Forgets the sign-in on this computer. |
graphicseditor-cli activate MGE1-XXXX-XXXX-XXXX |
Activates a permanent license key for the command line on this computer. |
graphicseditor-cli status |
Shows the account, the plan, and whether graphicseditor-cli can be used. |
You never type your password into the terminal: you sign in on the Motaware website in your browser, as you do in the app. After you sign in, login and status print the account and its plan, and end with graphicseditor-cli can be used. when everything is in order.
Note: A permanent license you activated in the app is not shared with the command line. Run
graphicseditor-cli activatewith the same key.
Using it with an AI assistant
The Model Context Protocol (MCP) is a standard way for AI assistants to use tools on your computer. graphicseditor-cli mcp runs an MCP server: an assistant that supports MCP can then open, draw, edit, look at and save Graphics Editor documents for you.
Adding it to Claude Code
Run this once in a terminal:
claude mcp add --scope user graphicseditor -- "C:\Program Files\Motaware\Graphics Editor\cli\graphicseditor-cli.exe" mcp
If you installed Graphics Editor into another folder, use the line that graphicseditor-cli --help prints instead: it names the program in your install. Use the full path, as shown. An assistant that was already running when you installed Graphics Editor still has the old PATH and would not find the program by name alone.
Other assistants
Any MCP client that can start a local server works. Give it:
- the command: the full path of
graphicseditor-cli.exe, as above; - one argument:
mcp; - the transport: standard input and output (stdio).
Signing in for the assistant
The server starts whether you are signed in or not. Until you are, every tool answers with how to sign in, and only account_status works. Run graphicseditor-cli login in a terminal: the running server picks up the sign-in at its next request, so you don't need to restart the assistant.
What an assistant can do
The server gives the assistant these tools.
| Group | Tools |
|---|---|
| Documents | document_info (artboards, layers, object counts, unsaved changes, what undo would do), new_document (size and number of artboards), open_document (a .mgfx, or an SVG, AI, EPS, PDF or PSD file imported as a new untitled document) |
| Drawing | create_objects (shapes, text and groups from object specs), add_svg (SVG markup or single SVG elements, as editable objects), add_layer, add_artboard |
| Looking at the work | list_objects, get_object, render_image (a picture of the whole document, or of one artboard as it exports) |
| Editing | modify_objects (any spec key, plus move, position, rotate and scale), delete_objects, duplicate_objects |
| Arranging | arrange (group, ungroup, bring to front, send to back, bring forward, send backward, move into a layer or group), align (left, centre, right, top, middle, bottom, distribute horizontally or vertically; relative to the objects or the artboard), pathfinder (unite, subtract, intersect, exclude) |
| Saving and exporting | save_document (.mgfx), export (SVG, PDF, PNG, JPEG, TIFF or WebP, with scale or dpi, transparency and a single artboard for images) |
| Undo | undo, redo |
| Scripts | run_script (JavaScript with the editor object, see Scripts) |
| Account | account_status |
The assistant works on one document at a time. Every change it makes is one undo step, and a change that fails leaves the document exactly as it was. Nothing is written to disk until the assistant saves or exports. Starting a new document or opening another one discards unsaved changes, so ask the assistant to save first if you want to keep the work. An imported file is a new untitled document, so saving it never overwrites the original SVG or PDF.
Coordinates are in points (1/72 inch), measured from the top-left corner of the first artboard, with y going down. A new document is 800 × 600 points unless you ask for another size. Objects without a parent go into the layer of the artboard they sit on.
Example prompts
- "Make a 1080 × 1080 social media post: a dark blue background, a large white headline 'Summer Sale' and a yellow star badge in the top right corner. Save it as C:\Work\sale.mgfx and export a PNG at 2x."
- "Open C:\Work\logo.svg, change every red to #0a6cff, and export it as a PDF."
- "Draw a row of five circles with a gradient from orange to pink, align them to the middle of the artboard and distribute them evenly."
- "Show me what the document looks like now." (The assistant uses
render_image.) - "Undo the last two changes."
When the assistant has saved the file, open it in Graphics Editor with File > Open… to keep working on it by hand.
Scripting from the command line
run
graphicseditor-cli run builds or changes one document and then saves and exports it. The options run in this order: open or create the document, place SVG files, run scripts, save, export.
| Option | What it does | Example |
|---|---|---|
--open FILE |
Starts from this .mgfx, or imports an .svg, .ai, .eps, .pdf or .psd file. |
--open logo.svg |
--new WxH[xN] |
Starts from a new document with N artboards of W × H points, side by side. Without --open or --new you get one 800 × 600 artboard. |
--new 1080x1080x3 |
--svg FILE |
Places this SVG file's artwork. You can repeat it. | --svg icon.svg |
--script FILE.js |
Runs a JavaScript file. You can repeat it. | --script poster.js |
-e CODE |
Runs this JavaScript. You can repeat it. | -e "editor.info()" |
--save FILE.mgfx |
Saves the result. | --save poster.mgfx |
--export FILE |
Exports by the file's extension: .svg, .pdf, .png, .jpg, .tiff or .webp. You can repeat it. |
--export poster.png |
--scale S |
Pixels per point for image exports. The default 1 is 72 dpi; 2 is 144 dpi. | --scale 2 |
--artboard N |
Exports only artboard N to images. The first artboard is 0. | --artboard 0 |
For example:
graphicseditor-cli run --new 1080x1080 --script poster.js --save poster.mgfx --export poster.png --scale 2
graphicseditor-cli run --open logo.svg -e "editor.modify(editor.list()[0].id, {fill: '#c00'})" --export logo.pdf
If a script fails, everything it did is undone and run stops with an error.
render
graphicseditor-cli render makes a PNG preview of a file: the whole document on a grey background with the artboard edges, or one artboard as it exports.
graphicseditor-cli render poster.mgfx preview.png --size 1600x1200
graphicseditor-cli render poster.mgfx first.png --artboard 0
The default size is 1600 × 1200 pixels.
Scripts
Scripts are JavaScript. Besides the usual language, they get an editor object for working with the document. Ids are returned by the methods that create objects; wherever an id is asked for, you can also give an object's name if it is unique.
| Method | What it does |
|---|---|
editor.create(spec, parent) |
Creates one object, or several from an array of specs. Returns the id or ids. parent (a layer, group or artboard) is optional. |
editor.addSvg(svg, options) |
Adds SVG markup. Options: x, y (where the left and top edges go), parent, group (several elements become one group, default true), name. Returns the ids. |
editor.modify(id, changes) |
Changes an object (see Changing objects). |
editor.remove(ids) |
Deletes objects. |
editor.duplicate(ids, dx, dy) |
Copies objects, offset by dx and dy (default 10, 10). Returns the copies' ids. |
editor.get(id) |
Describes one object in full. |
editor.list(filter) |
Lists objects. The filter can have type, name, parent and depth. |
editor.group(ids, name) |
Groups objects. Returns the group's id. |
editor.ungroup(id) |
Ungroups. Returns the ids of the former contents. |
editor.arrange(ids, action, target) |
bring_to_front, send_to_back, bring_forward, send_backward, or move_to with a layer or group as target. |
editor.align(ids, op, relativeTo) |
left, center, right, top, middle, bottom, distribute_horizontal, distribute_vertical; relative to "objects" (default), "artboard" or "artboard N". |
editor.boolean(ids, op) |
unite, subtract, intersect or exclude. The result takes the look of the back-most shape. |
editor.addLayer(name, artboard) |
Adds a layer on top of an artboard's layers. |
editor.info() |
Describes the document. |
console.log() prints a line. Object bounds are [left, top, width, height] in document points.
var id = editor.create({type: "star", cx: 100, cy: 100, outer_radius: 60, inner_radius: 25,
points: 5, fill: "#ffcc00", stroke: "none"});
var ids = editor.addSvg("<circle cx='300' cy='100' r='40' fill='tomato'/>", {x: 250, y: 50});
editor.modify(id, {rotate: 15, effects: [{type: "drop_shadow", dx: 4, dy: 4, blur: 8}]});
var g = editor.group([id].concat(ids), "Badge");
editor.align([g], "center", "artboard");
console.log(JSON.stringify(editor.get(g).bounds));
A script is one undo step. If it stops with an error, everything it did is undone. An AI assistant runs the same scripts with run_script.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Something failed, for example a file could not be read, a script failed, or a save or export failed. |
| 2 | The command or its options were wrong. |
| 3 | Not signed in, or the plan or license doesn't allow graphicseditor-cli. |
Object specs
Assistants and scripts describe objects as JSON. Coordinates are in points, y down, from the top-left corner of the first artboard.
Shapes
| Type | Keys |
|---|---|
rectangle |
x, y, width, height, corner_radius |
ellipse |
cx, cy, rx, ry |
circle |
cx, cy, r |
line |
x1, y1, x2, y2 |
polyline |
points ([[x, y], …]), closed (true or false) |
path |
d (SVG path data, for example "M10 10 C 20 0 40 0 50 10 Z") |
polygon |
cx, cy, radius, sides, rotation (degrees) |
star |
cx, cy, outer_radius, inner_radius, points, rotation (degrees) |
text |
x, y (the left end of the baseline), text, font_family, font_size, bold, italic, font_weight (100–900), letter_spacing |
group |
children (a list of specs) |
Since version 1.3.1, a line break written as \n in text starts a new line.
Keys for every object
| Key | Value |
|---|---|
name |
The object's name, as shown in the Layers panel. |
fill |
A colour, "none", or a gradient (below). |
stroke |
A colour, "none", or {"color", "width", "cap", "join", "dash", "opacity"}. cap is butt, round or square; join is miter, round or bevel; dash is a list of dash and gap lengths. |
stroke_width |
The stroke width in points. |
opacity |
0 to 1. |
blend_mode |
normal, multiply, screen, overlay, darken, lighten, color_dodge, color_burn, hard_light, soft_light, difference, exclusion, hue, saturation, color, luminosity. |
effects |
A list of effects (below), or [] to remove them. |
rotate |
Degrees, about the object's centre. |
transform |
[a, b, c, d, e, f], an SVG matrix applied after the shape. |
visible, locked |
true or false. |
Without fill and stroke, a closed shape gets a white fill and a 1 pt black stroke, an open one a 1 pt black stroke, and text a black fill.
Gradients
{"type": "linear", "x1": 0, "y1": 0, "x2": 1, "y2": 0, "stops": [[0, "#f00"], [1, "#00f"]]}
{"type": "radial", "cx": 0.5, "cy": 0.5, "r": 0.5, "stops": [[0, "white"], [1, "navy"]]}
Gradient positions run from 0 to 1 across the object's bounds. For a radial gradient, r is relative to the larger side. A gradient needs at least two stops.
Effects
| Effect | Keys |
|---|---|
drop_shadow |
dx, dy, blur, color |
inner_shadow |
dx, dy, blur, color |
outer_glow |
radius, color |
blur |
radius |
Colours
A colour can be "#rgb", "#rrggbb", "#rrggbbaa", "rgb(r, g, b)", "rgba(r, g, b, a)" or a CSS colour name such as "tomato".
Changing objects
modify_objects and editor.modify take the same keys. A shape's own keys (such as width, cx, text, font_size, or d for paths) are in the shape's own coordinates. They also take:
move:[dx, dy];position:[left, top], where the object's bounds go in the document;scale: a number, or[sx, sy], about the object's centre.
Setting a fill, stroke or effect on a group changes everything in it.