Command-line reference¶

The installed inklet command and python -m inklet use the same entry point. Run inklet --help or inklet <command> --help for the installed version's arguments.

Author script contract¶

A script supplies its figure in one of two ways. Define a factory, make_document() returning a Document, make_figure() returning a Figure, or make_chart() returning a chart; the first one defined, in that order, is called. Or leave a top-level Document, Chart, Layout, CompiledFigure or Figure. The loader picks that object by type, so other top-level values, such as a matplotlib fig or a pandas DataFrame, are ignored. If there are several, a top-level name chart, doc, fig or figure is preferred, in that order. Without such a name the single inklet object is used. Two or more unnamed inklet objects are an error, and so is a script with none; the error lists the top-level names it found. If a factory returns anything else, the build fails and names the factory and the type it returned.

import inklet as i

def make_document():
    doc = i.document(width=100)
    doc.add('message', i.component(i.text, 'Hello, Inklet'))
    return doc

The loader executes author code, including module-level code, then calls the factory. Put direct-run saves under if __name__ == '__main__': so loading a script does not create additional outputs. Sibling imports are supported.

Build once¶

inklet build examples/v25_document.py --output out/review --name document

The command compiles the figure and prints the resulting review path. Default output is out/review, with base name figure.

--vectors-only cannot be combined with --compare-to. Bundle export embeds fonts unless the document profile chooses outlined text; there is no CLI --text flag. Set the profile or use the Python export API.

A successful build exits zero even when the figure has diagnostic findings. Compilation/export failures exit nonzero. To enforce your own diagnostic policy, inspect compiled.diagnostics or the exported JSON in a validation script.

Watch and preview¶

inklet watch examples/v25_document.py --output out/review --name document \
  --watch data.csv --watch assets/ --port 8765

The server binds to 127.0.0.1, with default port 8765. Open the printed URL. Watch accepts the shared build options above except --vectors-only, plus:

Python files under the author script's directory are watched automatically. Explicit directories also include non-Python files. Hidden paths, __pycache__, node_modules and directories named out are excluded from recursive watching. After a successful bundle, Blender scene dependencies in its manifest are also watched. Other dependencies need --watch entries.

Each rebuild runs in a fresh Python process, with a 600-second default build timeout. The browser displays the last successful bundle if a build fails and shows the error alongside it. The next successful edit refreshes the preview. Stop with Ctrl-C.

Without --compare-to, successful watch builds compare against the preceding bundle. Supply a fixed reference to compare every revision against the same baseline. See revision review.

Check the environment¶

inklet doctor
inklet doctor --devices

Reports Python, Pillow, NumPy, resvg, Blender (path/version), Chrome/Chromium, Poppler and Fontconfig as JSON. --devices also starts a short Blender subprocess to list Cycles GPU backends, device IDs and discovery errors. It does not render a test scene. This command does not validate fonts or figure geometry, and missing optional tools do not cause a failing exit code. Use installation and troubleshooting to resolve missing dependencies.