Table of Contents

• Getting Help
• Commands
  • render
    • Argument
    • Options
    • Examples
  • batch
    • Options
  • types
    • Options
  • version
• Environment Variables
• Exit Behavior
• Next Steps

Complete reference for the Sirena command-line interface.

Getting Help

Running sirena without a command displays the command list. The root help forms below do the same:

sirena
sirena help
sirena -h
sirena --help

Use help with a command name for that command’s usage and options:

sirena help render
sirena help batch

The CLI also provides a command tree:

sirena tree

--help and -h are root-level help forms, not command options. For example, sirena render --help treats --help as the input file and fails if that file does not exist. Use sirena help render instead.

Commands

render

Render one diagram as SVG.

sirena render [FILE]

Argument

FILE

Optional diagram input file. When omitted, or when FILE is -, Sirena reads source from standard input. For a file, Sirena tries its registered extension before inspecting the source to select a notation.

Options

--output PATH, -o PATH

Write SVG to PATH. Without this option, SVG is written to standard output.

--format FORMAT, -f FORMAT

Output format. Defaults to svg; SVG is the only supported format.

--theme THEME, -t THEME

A built-in theme identifier or a path to a theme YAML file. Built-in themes are default, dark, light, and high_contrast.

--verbose, -v

Enable verbose output. It defaults to false. On an error, verbose mode also prints the backtrace.

--notation NOTATION

Use the named registered notation instead of detecting one from the file extension and then the source.

--require PATH, -r PATH

Load a notation file before rendering. This option is repeatable. Each file must register its notation with Sirena.

Examples

Render a file to an SVG file:

sirena render diagram.mmd -o diagram.svg

Render standard input, with either supported stdin form:

cat diagram.mmd | sirena render
cat diagram.mmd | sirena render -

Select SVG explicitly and use a built-in theme:

sirena render diagram.mmd -f svg -t dark -o diagram.svg
sirena render diagram.mmd -t high_contrast -o diagram.svg

Select a notation explicitly, or load one supplied by another file:

sirena render --notation mermaid diagram.txt
sirena render --require ./my_notation.rb diagram.my

batch

Render diagram files in a directory.

sirena batch [OPTIONS]

batch has no positional argument; use --input or -i to choose input.

Options

--input PATH, -i PATH

Input directory or file. Defaults to the current directory (.).

--output PATH, -o PATH

Output directory. Defaults to output.

--theme THEME, -t THEME

A built-in theme identifier or a path to a theme YAML file. There is no explicit option default.

--verbose, -v

Enable verbose output. It defaults to false.

--notation NOTATION

Restrict directory discovery and rendering to the named registered notation. Without this option, all registered notation extensions are included.

--require PATH, -r PATH

Load a notation file before discovering inputs. This option is repeatable.

When the input is a directory, Sirena recursively finds regular files whose case-insensitive extensions belong to the selected notation, or to any registered notation when --notation is omitted. It writes an .svg file under the output directory with the same relative path. Discovery excludes dotfiles and does not descend into hidden subdirectories of the selected input directory.

For example:

sirena batch -i diagrams -o output
sirena batch -i diagrams -o output -t dark
sirena batch -i diagrams -o output --notation mermaid
sirena batch -i diagrams -o output -r ./my_notation.rb

Batch status is reported in its summary. Current edge-case behavior is:

• A nonexistent input path finds zero files, prints No diagram files found in: PATH, and exits 0 — this counts as success (nothing failed), the same as an input directory with no registered diagram files in it.

• A direct file input renders that one file into the output directory even if its extension is not registered. A registered extension is replaced by .svg; an unregistered extension is retained.

• A file that fails to render does not stop later files. The summary records successes and failures, and the command exits 1 if any file failed, 0 if every file succeeded (including a run that found none).

types

List the diagram types registered by the current executable:

sirena types [OPTIONS]

Output begins with Supported diagram types:. It then groups identifiers under each registered notation. The built-in registration is:

mermaid:
  flowchart
  sequence
  class_diagram
  state_diagram
  er_diagram
  user_journey
  pie
  gantt
  timeline
  quadrant
  git_graph
  mindmap
  kanban
  radar
  block
  requirement
  xychart
  architecture
  sankey
  packet
  treemap
  c4
  info
  error

Options

--require PATH, -r PATH

Load a notation file before listing. This option is repeatable. Each additional notation is printed as another group.

version

Show the Sirena version:

sirena version
sirena --version
sirena -V

Each form prints:

sirena version 0.1.0

Environment Variables

The CLI does not currently read any SIRENA_* environment variables.

Exit Behavior

Successful commands and root help exit 0. Errors handled by render, such as a missing input file or an unsupported format, print Error: …​ and exit 1.

batch records individual render failures in its summary instead of aborting, then exits 1 if any file failed and 0 if every file succeeded — a missing input path or empty input directory counts as 0 files succeeding, 0 failing, so it exits 0 rather than 1.

Next Steps

• Diagram Types Reference - Syntax for all 24 types

• Quick Start Guide - Get started quickly

• Examples - Browse working examples