Command Line

Render

xaligo render <file.xal> --format <format> -o <output>

Supported formats:

The default is svg. Terminal output requires a V2 document. Retired format names are rejected as unknown formats. Markdown is handled by xaligo render markdown; it embeds SVG artifacts and is not a separate --format value.

Frames and physical pages

Identified child frames are physical pages for SVG and PPTX. They are emitted in source order.

Live SVG preview uses the combined canvas so every frame remains visible in one browser view. Markdown follows the SVG artifact mapping.

For a one-frame SVG document, -o is the exact output filename. For several frames, -o output/diagram.svg produces names such as output/diagram-overview.svg and output/diagram-detail.svg. Safe frame IDs retain ASCII letters, digits, _, and -; other character runs become -. Leading and trailing - are removed, an empty result falls back to the frame’s source order, and a filename collision is an error. SVG output is not wrapped in an implicit ZIP archive.

Common render flags:

Terminal flags:

Any mode, format, theme, orientation, paper size, arrow-style option, or SVG legend-position value outside its documented enum returns an error.

--arrow-style belongs to the shared physical plan used by SVG and PPTX.

Physical-page and PPTX flags:

--title sets package-level PPTX metadata. It is unrelated to the visible title attribute on a page <frame> and never creates a frame tag.

Structural Diff

xaligo diff before.xal after.xal -o output/architecture

The command compares parsed .xal data structures rather than source lines and writes two SVG images:

• output/architecture-removed.svg renders the old document and highlights removed elements plus the old side of modified or moved elements in pale red.
• output/architecture-added.svg renders the new document and highlights added elements plus the new side of modified or moved elements in pale green.

XML formatting, comments, attribute order, parser-private attributes, and the equivalent V1 forms with an omitted version or version="1" do not create a diff when that version is on the document root. A version on an identified child frame is visible page content and is compared normally, including the literal value 1. Matching prefers unique name, ref, and id values, then exact subtrees, followed by deterministic order-aware structural matching. Give elements an explicit id, name, or ref when moves must remain identifiable across different parents.

-o is an output prefix, not a single output filename. A trailing .svg is removed before -removed.svg and -added.svg are appended. The default prefix is output. --theme, --mode, and --px-per-inch are applied identically to both images. No difference is a successful result and still produces two unhighlighted SVGs.

See the structural diff sample for a complete before/after pair and the generated images.

Generate

Generate a starter .xal hierarchy:

xaligo generate xal -o generated.xal --paper A4 --orientation landscape

Useful generation flags:

Only --output is required. The generated file uses the canonical <xaligo version="1"><frames>...</frames></xaligo> document envelope.

SVG Icon Registry

The native CLI manages namespaced SVGs in the local xaligo-assets.db SQLite registry. The first icon operation installs 13 domain-neutral icons in the builtin namespace. Registrations are size-limited, safety-checked, and normalized by the in-process Rust engine before SQLite indexes their name, description, tags, and aliases with FTS5.

xaligo icon list --namespace builtin
xaligo icon search 'database OR storage'
xaligo icon get builtin:database -o database.svg
xaligo icon add router.svg --name network:router \
  --description 'Generic network router' --tag network --tag routing \
  --alias gateway --license MIT --source local
xaligo icon remove network:router
xaligo icon namespaces

Stable identities use namespace:name. icon add updates an existing identity atomically, including its tags, aliases, and search row. icon get writes SVG to standard output unless -o names a file. icon search accepts an FTS5 query and all list/search commands accept --limit up to 100. Configure the database path with paths.assets_db in etc/resources/aws/app.yaml.

Local RAG Index

The RAG command family builds a local SQLite/FTS5 knowledge index. Its initial corpus is intentionally restricted to Markdown files below docs/; .xal samples, the root README.md, source code, and generated documentation are not registered implicitly.

xaligo rag index
xaligo rag search 'database AND table'
xaligo rag search routing --limit 10 --json
xaligo rag symbols file:///path/to/diagram.xal
xaligo rag watch --interval 2s

rag index hashes each Markdown source and skips unchanged documents. It removes stale rows for deleted documentation files. rag watch runs the same incremental pass repeatedly. The shared project service can analyze an explicit .xal document into generic Frame, Group, Capture, Item, Port, Line, Text, and Spacer concepts for editor or agent requests, but that explicit path does not broaden the initial RAG corpus.

Language Server

xaligo lsp runs the in-process Language Server Protocol 3.18 adapter over standard input and output. It uses Content-Length framed JSON-RPC and keeps all ordinary logs on standard error so protocol output remains clean.

xaligo lsp

The server provides full-document synchronization, push and pull diagnostics, hierarchical document symbols, project-backed workspace symbols, semantic tokens, completion snippets, definition and reference navigation, and hover details over tags and semantic identifiers. It reuses the same parser and generic concept analysis as the project service rather than maintaining an editor-only parser. Saving an open .xal file is an explicit editor operation and updates that document’s concept rows; it does not make .xal part of rag index, whose initial corpus remains only docs/**/*.md and docs/**/*.markdown.

Other Commands