Commands

tdsl handles validation, compilation to JSON IR, HTML rendering, Wikidata-based timeline generation, and template scaffolding for .tdsl files.

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 | | tdsl lint <FILE> | Run a quality check | | 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+) | | 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+).

tdsl decompile sample.json --output sample.tdsl

merge

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

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

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.

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).

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 three precisions — YYYY, YYYY-MM, and YYYY-MM-DD (month/day precision is supported from v1.10.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. The 8-column subset round-trips with import-csv. The source / origin columns are kept for reference but ignored by import-csv.

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 list            # List cached entries
tdsl cache clear           # Delete all cached entries
tdsl cache clear --dry-run # Preview what would be deleted (without actually deleting)

| Command | Description | | ------------------ | ----------------------------------- | | tdsl cache list | Show cached entries and their sizes | | tdsl cache clear | Delete all cache entries |

The cache is stored under the OS data directory (data_dir from the dirs crate). 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 | render | Set the layout style. group-bands draws era/group background bands (default timeline; v1.23.0+) | | --show-legend | render | Add a static legend panel showing lane and tag colors (v1.23.0+) | | --format text,json | lint | Specify the output format for lint results | | --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 after the SVG (HTML format only; v1.16.0+) | | --json-schema | build | Write the JSON Schema for TimelineIr to stdout (or --output); no input file required (v1.16.0+) |