The napkin-sketch command line#

API hub · Reference · Quickstart · Cheatsheet

napkin-sketch draw turns a napkin script into files - SVG, PNG, PDF, a .skbk the app opens, or an Illustrator script - with no window, and without loading Electron at all. check reads and runs a script and writes nothing, render writes a sketch book the app saved, and verbs lists the language. This page is the reference for the four commands, their exit codes and their JSON report, and for calling them from other languages.

Contents

• What this is
• The mental model
• Reference
  • draw
  • check
  • render
  • verbs
  • Exit codes
  • The JSON report
  • Standard input and the object form
  • Names, folders and links
• Worked examples
• Limits
• For agents
• See also

What this is#

The app's command line opens the drawing window, and four commands beside it never do. They are for programs: a build step, a batch file, a Python or C program, an agent. Each takes a script from a file or from standard input, writes files into a folder, and reports in one of two ways - for a person, with problems on standard error and the files written on standard output, or with --json, as one line of JSON on standard output and nothing else.

Any language that can start a process can draw this way, and needs nothing else: no library, no binding, no temporary file. The commands reach no part of Electron, so they also work where a global install left the drawing window unable to start.

The mental model#

 card.napkin --+                        +--> out/card.svg  out/card.png  out/card.pdf  out/card.skbk
               +--> napkin-sketch draw --+
 stdin (-) ----+                        +--> stdout: the files written, or one line of JSON
                                        +--> stderr: problems, as file:line:column: level code: message
                                        +--> exit code: 0 drew, 1 arguments, 2 the script, 3 a file, 4 the AI helper

Reference#

draw#

napkin-sketch draw <script | -> [--to svg,png,pdf,skbk,jsx] [--out <dir>] [--name <stem>]
                   [--base <dir>] [--asset <name>=<file> ...] [--use <name>=<book.skbk> ...]
                   [--font <family>=<file> ...] [--composition-style <style.json>]
                   [--seed <n>] [--scale <n>] [--crop auto|none|<x,y,w,h>] [--limit <n>]
                   [--json] [--strict] [--quiet]
napkin-sketch draw --prompt "<request>" [--helper <command>] [the options above]

Both --to svg,png and --to=svg,png work, and a value may start with one -, as --seed -3 does. A script's own crop and registration apply unless --crop is given.

With --prompt, an AI tool writes the script: napkin-sketch writes a form to _temp/script-form.txt, runs the helper command in the current folder, reads the script it saves to _temp/script-out.napkin, checks it, and sends it back once with its diagnostics when it has errors. The script is kept beside the files as <name>.napkin, and printed first in the list; the --asset, --use and --base it is checked and drawn with are read from the current folder, as for a script on standard input.

check#

napkin-sketch check <script | -> [--base <dir>] [--asset <name>=<file> ...] [--use <name>=<book.skbk> ...]
                    [--seed <n>] [--limit <n>] [--json] [--strict] [--quiet]

Reads and runs the script exactly as draw would, writes nothing, and prints what it found, ending with a line such as card.napkin: 1 error, 0 warnings or card.napkin: no problems. A warning alone passes; --strict fails it. Give it the same --asset and --use the drawing will get, or a script that places an image reports unknown-asset.

render#

napkin-sketch render <book.skbk> [--to svg,png,pdf,skbk,jsx] [--page <n>] [--out <dir>] [--name <stem>]
                     [--base <dir>] [--font <family>=<file> ...] [--scale <n>] [--crop auto|none|<x,y,w,h>]
                     [--json] [--strict] [--quiet]
napkin-sketch render <book.skbk> --animate <type> [--frames <n>] [--facing left|right] [--page <n>]
                     [--to ...] [--out <dir>] [--name <stem>] [--base <dir>] [--scale <n>] [--json] [--strict] [--quiet]

Writes a sketch book - one the app saved, or one draw wrote - as files named after the book's file. --page 2 writes page 2 alone, still named for its place in the book: deck-2.png. The .skbk may be left off the name, as the app's own --book allows. --font hands it font files as draw takes them.

--animate walk writes the figure on the page as animation frames instead, drawn from the measured walk cycle with no AI. The figure is found as Animation Mode finds it, by its assemblies' layer names - front-arm-assembly, body, front-leg-assembly, back-leg-assembly, back-arm-assembly and head - and each part is copied onto a page a frame and turned about its joint by the cycle's total up to that frame. hero.skbk gives a file a frame, hero-walk-1.svg to hero-walk-8.svg, every one cut to the same box - the union of the frames' ink - so they play back without shifting; --name sets the stem, and a PDF, .skbk or .jsx holds every frame. The types are the four with a measured cycle: walk, run, ideal - the app's Idle, and idle is read as it - and knocked-down. --frames 4 spreads the cycle across four frames rather than its own eight, so each moves further, and --facing left or right says which way the figure travels, which is otherwise read from its feet. The JSON report carries the script that drew the frames as script.text, and a page with none of the assemblies exits 2.

verbs#

napkin-sketch verbs [--category <name>] [--json]

Lists the language by category, each verb as it is written with what it does, and the names the shape library draws. --category shapes narrows it to one category. --json gives the whole table as one line: the verbs with their grammar, the categories, the shapes, and every diagnostic code with its level - which is the language's reference in one call.

Exit codes#

Errors in a script are values, reported and passed over: a script with a mistyped verb still draws everything else, and exits 2 so that a caller knows.

The JSON report#

With --json, draw, check and render print one line like this, spread over lines here to read:

{
  "ok": false,
  "exitCode": 2,
  "files": [
    { "path": "out/card.svg", "format": "svg", "page": 1 },
    { "path": "out/card.png", "format": "png", "page": 1 }
  ],
  "diagnostics": [
    { "level": "error", "code": "unknown-verb", "message": "`circl` is not a verb. Did you mean `circle`?", "line": 4, "column": 1 }
  ],
  "warnings": [],
  "stats": { "instructions": 4, "marks": 1, "anchors": 8, "points": 101, "pages": 1 },
  "version": "1.0.0-alpha.5.0.0",
  "language": 1
}

verbs --json prints the language's table instead: categories, verbs, shapes, and, for the whole language, diagnostics.

Standard input and the object form#

- reads the script from standard input, which is how a program hands one over without a temporary file. Text starting with [ is the object form, a script built as JSON; anything else is napkin script text. A file ending .json is the object form too. Text that is not JSON, or JSON that is not an array, is reported as an unexpected-token or invalid-value diagnostic, with exit code 2.

Names, folders and links#

• The files' name is --name, else the script's own name, else the script file's name, card for card.napkin, else drawing. A book of one page writes card.svg; several write card-1.svg, card-2.svg and on. A PDF, a .skbk or a .jsx is one file for the whole book.
• A name never leaves --out. A script names its own pages, so a name is made a file name first: every character a file name cannot hold becomes -.
• Paths on the command line - the script, --out, --asset, --use - are read from the current folder, as a shell expects.
• Links are read inside --base only, the script's folder unless given: no absolute path, .. step or web address. A link that cannot be read is drawn as its placeholder, the files are still written, and the command exits 3, naming the link. A .jsx reads no link as it is written: it names each linked file by its path from --out through --base, and Illustrator places the file from there when the script runs.

Worked examples#

Each caller below is a real file in examples/, drawing examples/card.napkin, and the test suite runs each one wherever its shell, interpreter or compiler is installed.

• draw.sh - a shell script that branches on the exit code, then hands the same script over on standard input with --json.

• draw.bat - a Windows batch file. It must call napkin-sketch, since npm installs it as a .cmd file and a batch file that runs another one without call never comes back.

• draw.mjs - Node's child_process, with the script on standard input and the JSON line read back. A Node program that can import the package does better with @isocialpractice/napkin-sketch/node; see Using napkin-sketch from code.

• draw.py - Python's subprocess.run with input= and --json:

  result = subprocess.run(
      [shutil.which("napkin-sketch"), "draw", "-", "--json", "--to", "svg,png", "--out", "out"],
      input=script, capture_output=True, encoding="utf-8",
  )
  report = json.loads(result.stdout)

• draw.c - C's popen, reading the one JSON line.

A folder of scripts, each drawn to SVG and PNG, with the failures named:

for f in scripts/*.napkin; do
  napkin-sketch draw "$f" --to svg,png --out out --quiet || echo "$f: exit $?" >&2
done

Get-ChildItem scripts -Filter *.napkin | ForEach-Object {
  napkin-sketch draw $_.FullName --to svg,png --out out --quiet
  if ($LASTEXITCODE -ne 0) { Write-Error "$($_.Name): exit $LASTEXITCODE" }
}

A check in CI, failing the build on any problem, warnings included:

napkin-sketch check card.napkin --strict --asset logo=art/logo.png

Limits#

• One script a call. A host drawing hundreds of graphics starts a process for each; a long-lived mode that takes a request a line on standard input is not built yet.
• render reads a file, not standard input.
• No pad on the command line. --crop auto is the ink with no room around it; a script's own crop auto pad 12 gives the room.
• Assets and documents are read as given, with no folder guard, since the caller names them; only links, which the script names, are kept to --base.
• A book must be a .skbk. render does not import an SVG or a PDF; the app does that.

For agents#

• Use --json, and read one line. Branch on exitCode - 2 means fix the script, 3 means fix the files or the paths, 4 means the AI helper behind --prompt gave back no script - and match diagnostics on code, never on message.
• Hand the script over on standard input with -, rather than writing a temporary file.
• Run check while writing a script, then draw once it is clean: it runs the same evaluation and writes nothing.
• Get the whole language with napkin-sketch verbs --json: every verb's grammar, the categories, the shape names and the diagnostic codes, in one call.
• Set --strict in CI, where a drawing with a placeholder or a warning is worse than none.
• Pass images with --asset, never as paths inside the script: a script reads no files, and says unknown-asset when it names one it was not given.

See also#

• Using napkin-sketch from code: the same drawing from Node, with drawFile and drawToFiles.
• Writing a drawing out: the formats, the box, and what each format keeps.
• The napkin script language: the syntax, the object form and every diagnostic code.
• Drawing with napkin script: what each instruction draws.
• src/cli/draw.ts and src/cli/args.ts: the commands and their arguments.