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 activate with 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.