CLI reference
The ink command draws diagrams on your machine. It never downloads a browser, so it starts quickly and runs in small CI containers. Install it with npm install -g inkline or see Install for Homebrew, winget and Docker.
ink render
Draws one or more .ink files.
$ ink render checkout.ink -o checkout.png --scale 2
$ ink render docs/*.ink --format svg
$ ink render checkout.ink -o checkout.pdf --theme light
| Flag | Meaning | Default |
|---|---|---|
-o, --output <file> | Output file. The extension picks the format. Single input only. | next to the input |
-f, --format <format> | svg, png, jpg, webp or pdf | from -o, else svg |
-s, --scale <n> | Pixel density 1–4 for PNG, JPEG and WebP | 1 |
-w, --width <px> | Target pixel width for raster formats (overrides --scale) | — |
-q, --quality <n> | JPEG / WebP quality 1–100 | 90 |
-t, --theme <name> | slate, light, dark or ink (overrides the file) | from the file |
-l, --layout <direction> | right, down, left or up (overrides the file) | from the file |
-b, --background <value> | theme, transparent or a hex colour such as #ffffff | theme |
-p, --padding <px> | Space around the diagram, 0–400 | 24 |
JPEG has no transparency, so a transparent background is flattened to white.
ink watch
Re-renders when files change. With --serve, opens a live preview at http://localhost:4400 that redraws when you save.
$ ink watch "docs/**/*.ink" --serve
$ ink watch checkout.ink --format png --scale 2
Takes the same drawing flags as ink render, plus --serve and --port <n>.
ink validate
Checks files without drawing them, for CI. Prints every problem with its code and position and exits with a non-zero code if any file has an error.
$ ink validate "docs/**/*.ink"
ink fmt
Formats files in place: consistent indentation and spacing, comments kept. Formatting twice gives the same result as formatting once.
$ ink fmt "docs/**/*.ink"
$ ink fmt --check "docs/**/*.ink" # CI: exit 1 if a file needs formatting
ink convert
Converts Mermaid flowcharts and sequence diagrams to Inkline text, and Inkline back to Mermaid. draw.io and PlantUML are planned.
$ ink convert flow.mmd -o flow.ink
$ ink convert checkout.ink --to mermaid
ink init
Writes a starter example.ink in the current folder, or starts from a template.
$ ink init
$ ink init --list-templates
$ ink init --template url-shortener
$ ink init -t chat-system -o docs/chat.ink
| Flag | Meaning |
|---|---|
-t, --template <name> | Start from a template; writes <name>.ink |
--list-templates | List templates by category (system design, cloud, security, …) |
-o, --output <file> | File to write instead |
--force | Replace the file if it exists (otherwise exit 2 and nothing is written) |
The templates are the same ones as the web gallery (package @inkline/templates). AI-system, class and state templates arrive with the next engine release.
Cloud: ink login, push, pull, share
These commands connect a folder of .ink files to Inkline cloud. Your files stay the source of truth; the cloud keeps versions and makes share links.
ink login
$ ink login # prints a code, opens the browser; approve it there
$ ink login --no-browser # only print the link (SSH sessions, containers)
$ ink login --token ink_… # use a personal API token instead
$ ink whoami # who am I signed in as?
$ ink logout # revoke the session and forget it
ink login shows a short code such as BCDF-GHJK and opens the sign-in page; approve it in the browser and the terminal says Signed in as you@example.com. The session is stored in %APPDATA%\inkline\credentials.json on Windows, or ~/.config/inkline/credentials.json on macOS and Linux ($XDG_CONFIG_HOME is honoured), readable only by you. It renews itself; when it can no longer be renewed you are asked to run ink login again. The CLI never prints your tokens.
In CI, set INKLINE_TOKEN to a personal API token (create one under Settings → API tokens). It overrides any stored login.
ink push
$ ink push docs/checkout.ink
Pushed docs/checkout.ink → v1 (0193…)
$ ink push docs/checkout.ink # after editing: saves v2
$ ink push db.ink --workspace team --folder "Data" --title "Shop database"
The first push creates the diagram (in your personal workspace unless you pass --workspace with an id, slug or name) and links the file to it in .inkline/links.json. Later pushes save a new version. The link file lives at the project root: the nearest folder above the file that contains .inkline/, package.json or .git (your home folder never counts), or the file's own folder if there is none. Commit it so teammates push to the same diagrams.
If someone changed the diagram in the cloud since your last push or pull, the push stops:
The cloud copy changed since your last push/pull (you have v3, cloud is v5). Your local edits are kept.
To take the cloud copy, run `ink pull docs/checkout.ink --force` (your version is saved as
docs/checkout.local-<timestamp>.ink first); to replace the cloud copy with yours, run
`ink push docs/checkout.ink --force`.| Flag | Meaning |
|---|---|
--workspace <id|slug|name> | Workspace for a new diagram (default: your personal one) |
--folder <id|name> | Folder for the diagram (moves a linked diagram) |
--title <title> | Title (default: the file name); renames a linked diagram |
--force | Overwrite the cloud copy even if it changed |
--new | Ignore the existing link and create a new diagram |
ink pull
$ ink pull 0193… # writes <title>.ink in the current folder and links it
$ ink pull 0193… -o docs/flow.ink
$ ink pull docs/checkout.ink # refresh a linked file with the latest cloud version
ink pull never silently drops local work. .inkline/links.json records a SHA-256 of each file as you last pushed or pulled it, so pull can tell whether the file changed since:
- unchanged since the last push/pull: it is replaced with the cloud copy;
- already identical to the cloud copy (line endings aside): only the link is updated;
- edited and never pushed (or linked before hashes were recorded, and different from the cloud): pull stops with exit code 1 and leaves the file alone. Run
ink pushfirst, orink pull … --force, which first copies your version to<name>.local-<YYYYMMDD-HHMMSS>.inkin the same folder and prints its path; - an existing file not linked to this diagram: pull stops; choose another name with
-o, or pass--force(your file is backed up the same way).
ink share
$ ink share docs/checkout.ink
http://localhost:3000/v/…
$ ink share docs/checkout.ink --access comment --expires 7d
Prints a public link anyone can open without an account. --access is view (default) or comment; --expires takes an ISO date (2026-12-31) or a duration (12h, 7d, 2w). The link is shown only once; you can revoke it in the web app.
Servers
The API is --api-url, else INKLINE_API_URL, else the server you logged in to, else http://localhost:5080. Share links point at --web-url, else INKLINE_WEB_URL, else http://localhost:3000. A stored login is only sent to the server it was made for.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | The diagram has errors, a check failed, or a cloud command failed (not signed in, conflict, API unreachable) |
2 | Wrong command-line usage |
Planned commands (from, ai, mcp) print the roadmap week they arrive in.