Commands

tdsl handles validation, compilation to JSON IR, HTML rendering, Wikidata-based timeline generation, and template scaffolding for .tdsl files. See the CLI Reference for the detailed arguments and options of each subcommand.

tdsl --help
tdsl help <command>

Basic Workflow

tdsl check sample.tdsl
tdsl lint sample.tdsl
tdsl build sample.tdsl --pretty --output sample.json
tdsl render sample.tdsl --output sample.html

Command	Description
tdsl check <FILE>...	Run a syntax and semantic check (multiple files/directories, v2.0.0+)
tdsl lint <FILE>...	Run a quality check (multiple files/directories, v2.0.0+)
tdsl build <FILE>	Compile .tdsl to IR JSON
tdsl render <FILE>	Render to a standalone HTML file
tdsl ast <FILE>	Output the AST for debugging
tdsl decompile <FILE>	Decompile JSON IR back to .tdsl (v1.1.0+)
tdsl merge <FILES...>	Merge multiple .tdsl files into one (v1.2.0+)
tdsl completions <SHELL>	Generate shell completion scripts (v1.9.0+)
tdsl lsp	Start the language server (LSP) (v1.11.0+)
tdsl fmt <FILE>...	Format .tdsl to the canonical style (v1.14.0+; multiple files/directories from v2.0.0+)
tdsl export-csv <FILE>	Export IR to CSV (v1.23.0+)

build and render may perform network access when processing files that include Wikidata imports. Use --offline if you only want to process locally-defined items.

tdsl build sample.tdsl --offline --pretty
tdsl render sample.tdsl --offline --output sample.html

decompile

Reverse-generates .tdsl source from a JSON IR. This is the inverse of build, useful when you want to recover DSL source from an existing IR (v1.1.0+). Second precision and UTC offsets (Z / ±HH:MM) in start / end / time also round-trip without loss (v1.27.0+; earlier versions silently dropped them).

tdsl decompile sample.json --output sample.tdsl

merge

Merges multiple .tdsl files and outputs a combined IR JSON. Useful when you manage lanes or events across separate files and want to combine them into a single IR (v1.2.0+).

tdsl merge part1.tdsl part2.tdsl --output combined.json --pretty

render

Renders .tdsl to a standalone HTML, SVG, PNG, or PDF file. Use --format to choose the output format. --format png is supported from v1.10.0+; --format pdf from v1.11.0+.

tdsl render sample.tdsl --format svg --output sample.svg
tdsl render sample.tdsl --format png --output sample.png
tdsl render sample.tdsl --format pdf --output sample.pdf

PNG output rasterizes the internal SVG with resvg. CJK lane labels are rendered as long as the host environment has system fonts available (Noto Sans JP, Hiragino Sans, Yu Gothic, etc.). Use --dpi (default 96) to set the rasterization resolution, or --png-scale to set a fixed pixel scale multiplier. --dpi and --png-scale are mutually exclusive (v1.11.0+).

PDF output produces a vector-format file suitable for printing and high-resolution display (v1.11.0+).

Pass --orientation vertical to draw the time axis top-to-bottom in a vertical layout (default horizontal, v1.13.0+). All output formats (HTML / SVG / PNG / PDF) are supported.

tdsl render sample.tdsl --orientation vertical --output sample.svg

Pass --grid to draw grid lines in the background aligned to the tick marks. Choose the interval with decade / year / month, or none (default) to hide them (v1.14.0+). Both horizontal and vertical layouts are supported. Grid lines are drawn faintly and, as decorative elements, are hidden from assistive technologies. Since the default is none, existing output is unchanged.

tdsl render sample.tdsl --grid decade --output sample.svg

completions

Generates shell completion scripts you can source. Supports bash / zsh / fish / pwsh / elvish (v1.9.0+).

# bash
tdsl completions bash >> ~/.bashrc

# zsh
tdsl completions zsh > ~/.zfunc/_tdsl

# fish
tdsl completions fish > ~/.config/fish/completions/tdsl.fish

lsp

Starts the Timeline DSL language server (LSP) over stdio (v1.11.0+). Once connected from your editor’s LSP client, you get real-time diagnostics, context-aware completion, hover, goto-definition, references, rename, code actions, document symbols, and formatting while editing .tdsl files. The VS Code extension connects automatically from v1.19.0 onwards. From v1.27.0 onwards, hovering over a time literal also shows its precision (e.g. date-time (second)) and whether it carries a timezone offset.

tdsl lsp

Code actions (quick fixes) auto-fix with the same output as tdsl lint --fix. Only fixable lint issues (start_gt_end / invalid_tags / missing_id) are covered. Comments are preserved where possible, although comments inside blocks may be relocated to canonical positions.

tdsl lsp takes no arguments and speaks the LSP JSON-RPC protocol over standard input/output. See Installation for editor configuration (Neovim / Helix / VS Code), how each feature behaves, and the fixable / non-fixable lint details.

fmt

Formats .tdsl to the canonical style (2-space indentation, one blank line between blocks) (v1.14.0+). By default it writes the formatted result to standard output. Use --write to overwrite the file in place, or --check to exit non-zero when there is a diff (for CI). Also accepts multiple files and directories (see CLI Reference for details, v2.0.0+).

tdsl fmt sample.tdsl           # Write the formatted result to stdout
tdsl fmt sample.tdsl --write   # Overwrite the file in place
tdsl fmt sample.tdsl --check   # Fail when there is a diff (for CI)

It uses the same formatting engine as tdsl lint --fix, the LSP document formatting, and the WebUI Format button. Comments (// and /* */) are preserved, although comments inside blocks may be relocated to canonical positions.

Starting from Wikidata

Search for candidate QIDs on Wikidata, verify the timeline-relevant information, then generate a .tdsl scaffold.

tdsl search "Han dynasty" --lang en -n 5
tdsl inspect Q7209 --lang en
tdsl scaffold wikidata \
  --qids Q7183,Q7209 \
  --timeline "Chinese Dynasties (generated)" \
  --lang en \
  --target auto \
  --lane-mode per-entity \
  --output china.tdsl
tdsl render china.tdsl --output china.html

Command	Description
tdsl search <QUERY>	Search Wikidata for candidate QIDs
tdsl inspect <QID>	Verify the timeline plan for a QID
tdsl fetch <QID>	Display data for a Wikidata entity
tdsl resolve <URL>	Resolve a Wikipedia article URL to a Wikidata QID
tdsl scaffold wikidata	Generate a .tdsl scaffold from multiple QIDs

search, inspect, and resolve support --json for use in CI or integration with other tools.

Starting Manually

Create an empty timeline and add entries via CSV.

tdsl init \
  --output manual.tdsl \
  --timeline "Fictional World Timeline" \
  --range-start 1000 \
  --range-end 1300 \
  --lanes "kingdom:kingdom,incidents:incidents"

tdsl import-csv items.csv --append manual.tdsl
tdsl lint manual.tdsl --fix
tdsl render manual.tdsl --output manual.html

import-csv takes a UTF-8 CSV with a header row of lane,type,start,end,time,label,tags,id. The start / end / time columns accept the date-only precisions YYYY, YYYY-MM, and YYYY-MM-DD, plus the datetime precisions YYYY-MM-DDTHH:MM and YYYY-MM-DDTHH:MM:SS, and UTC offsets (Z / ±HH:MM) (month/day precision from v1.10.0+; time/second/offset follow the DSL’s own time-literal parser). The source / origin columns are independently optional, so a 9-column CSV with only one of them is accepted too, and the 10-column CSV produced by export-csv (with both) round-trips as-is (v1.26.0+).

export-csv

Exports an IR (from .tdsl or .json) to CSV (v1.23.0+). Writes the 8 columns accepted by import-csv (lane,type,start,end,time,label,tags,id) plus source / origin, for a total of 10 columns. All 10 columns, including source / origin, round-trip with import-csv (v1.26.0+). Second precision and UTC offsets (Z / ±HH:MM) in start / end / time also round-trip without loss (v1.27.0+; earlier versions silently dropped them). Rows with origin=wikidata require source to be in the wd:Q<id> form; a mismatch produces a CSV row-numbered error.

tdsl export-csv manual.tdsl --output manual.csv
tdsl export-csv manual.tdsl --offline --output manual.csv

Cache Management

tdsl build / tdsl render cache Wikidata fetch results locally. Use the tdsl cache subcommand to manage the cache (v1.1.0+).

tdsl cache status               # Show cache statistics (entry count, total size, oldest/newest entry)
tdsl cache clear                # Delete all cached entries
tdsl cache clear --older-than 7 # Delete only entries older than 7 days

Command	Description
tdsl cache status	Show cache statistics
tdsl cache clear [OPTIONS]	Delete cache entries
--older-than <DAYS> (clear)	Only delete entries older than this many days (default: deletes all)

The cache is stored under the OS cache directory (cache_dir from the dirs crate), e.g. ~/.cache/tdsl/. Pass --no-cache to bypass the cache and re-fetch from Wikidata.

Common Options

Option	Applies To	Description
--pretty	build	Pretty-print the JSON output
--output, -o	build, render, init, import-csv	Specify the output path
--offline	build, render	Skip Wikidata fetching
--no-cache	build, render	Re-fetch from Wikidata without using the cache
--cache-ttl <seconds>	build, render	Specify the TTL for the Wikidata cache
--wikidata-timeout <seconds>	build, render, search, inspect	Set the HTTP timeout for Wikidata requests (v1.4.0+)
--format html,svg,png,pdf	render	Specify the output format (default html; --format pdf from v1.11.0+)
--dpi <number>	render	Rasterization DPI for PNG output (default 96; mutually exclusive with --png-scale; v1.11.0+)
--png-scale <multiplier>	render	Fixed pixel scale multiplier for PNG output (mutually exclusive with --dpi; v1.11.0+)
--orientation horizontal,vertical	render	Specify the timeline orientation (default horizontal; v1.13.0+)
--grid decade,year,month,none	render	Draw grid lines in the background (default none; v1.14.0+)
--show-event-labels	render	Always draw labels for event / event_range items (v1.17.0+)
--lane-height <px>	render	Set lane height and vertical density (default 60; v1.21.0+)
--layout-style timeline,group-bands,gantt,zigzag	render	Set the layout style. group-bands draws era/group background bands, gantt emphasizes the month grid and always shows period labels, zigzag alternates item placement above/below the lane axis (zigzag only applies when there are at most 2 lanes; otherwise it falls back to timeline) (default timeline; group-bands from v1.23.0+, gantt / zigzag from v1.24.0+)
--show-legend	render	Add a static legend panel showing lane and tag colors (v1.23.0+)
--format text,json	check, lint	Specify the output format for diagnostics (check from v2.0.0+)
--deny-warnings	check	Exit non-zero when any warning is reported (by default, warnings alone still succeed; v2.0.0+)
--fix	lint	Apply safe fixes to the file
--write	fmt	Overwrite the file with the formatted result (v1.14.0+)
--check	fmt	Exit non-zero when there is a diff (for CI; v1.14.0+)
--watch	render	Watch the input file and re-render automatically on change (html / svg only; v1.16.0+)
--show-table	render	Append a chronological item listing table. An HTML <table> with --format html, or an equivalent SVG-drawn table below the timeline with svg / png / pdf (v1.16.0+)
--pdf-pagination	render	Split the --show-table item table onto separate PDF pages (requires --show-table; --format pdf only; when combined with --chart-pagination, the table pages follow all chart pages; v1.27.0+)
--chart-pagination <N>	render	Split the chart body into multiple pages by lane group, N lanes per page (requires --output; svg produces multiple <stem>.pageN.svg files, pdf produces multiple pages within a single PDF; v1.28.0+)
--chart-pagination-range <N>	render	Split the chart body into N pages along the time-range axis (requires --output; exclusive with --chart-pagination; svg produces multiple <stem>.pageN.svg files, pdf produces multiple pages within a single PDF; v2.0.0+)
--json-schema	build	Write the JSON Schema for TimelineIr to stdout (or --output); no input file required (v1.16.0+)