CLIリファレンス

tdsl は .tdsl ファイルのコンパイル・検証・整形・レンダリングを行うコマンドラインツールです。グローバルオプション・終了コード・主要サブコマンドの引数とオプションをリファレンス形式でまとめます。

tdsl [OPTIONS] <COMMAND>

--wikidata-timeout はグローバルオプションのため、サブコマンドの前後どちらに置いても有効です（例: tdsl --wikidata-timeout 60 build sample.tdsl）。

グローバルオプション

オプション	説明	デフォルト
--wikidata-timeout <SECONDS>	Wikidata HTTP リクエストのタイムアウト秒数	30
-h, --help	ヘルプを表示する	—
-V, --version	バージョンを表示する	—

終了コード

コード	意味
0	正常終了
1	エラー（パース失敗・バリデーション失敗・IO エラーなど）

tdsl check や tdsl fmt --check は CI のゲートとして使えます。差分やエラーがあれば終了コード 1 を返すため、パイプラインの成否判定にそのまま利用できます。

サブコマンド一覧

サブコマンド	概要
build	.tdsl → IR JSON にコンパイル
merge	複数 .tdsl ファイルを統合して IR JSON を出力
check	構文・意味エラーチェック
ast	パース済み AST をダンプ（デバッグ用）
fetch	Wikidata エンティティのデータを取得・表示
search	キーワードで Wikidata エンティティを検索
inspect	Wikidata エンティティを詳細解析してマッピング戦略を提案
resolve	Wikipedia 記事 URL を Wikidata QID に変換
scaffold	Wikidata エンティティから .tdsl テンプレートを自動生成
render	.tdsl をスタンドアロン HTML/SVG/PNG/PDF 年表にレンダリング
init	手動編集用の最小 .tdsl テンプレートを生成
import-csv	CSV から年表アイテムを取り込む
export-csv	IR を CSV に書き出す（import-csv と対称）
fmt	.tdsl ファイルを正準フォーマット
lint	.tdsl ファイルのリントと自動修正
cache	Wikidata ローカルキャッシュの管理
decompile	JSON IR を .tdsl ソースに逆変換
completions	シェル補完スクリプトを生成
lsp	LSP サーバを stdio 経由で起動（Diagnostics + Completion + Hover + Goto Definition + Code Action + Document Symbols + Find References + Rename + Formatting）

build

.tdsl ファイルを IR JSON（中間表現 JSON）にコンパイルします。複数ファイルを指定すると、マージしてから出力します。

tdsl build [OPTIONS] [FILE]...

引数

引数	説明
[FILE]...	入力 .tdsl ファイルのパス（複数指定時は順番にマージ）。--json-schema を指定する場合は省略可能

オプション

オプション	説明	デフォルト
-o, --output <OUTPUT>	出力 JSON ファイルのパス	標準出力
--pretty	JSON を整形出力する	—
--offline	Wikidata フェッチをスキップし、静的アイテムのみ処理する	—
--no-cache	ローカルキャッシュをバイパスして API を直接呼び出す	—
--cache-ttl <CACHE_TTL>	キャッシュ有効期限（秒）。0 で無効化	86400（24時間）
--json-schema	IR の JSON Schema を標準出力する（入力ファイル不要）	—

実行例

# オフラインでコンパイルし整形 JSON を表示
tdsl build examples/china_dynasties.tdsl --pretty

# Wikidata 連携ありでコンパイルしファイルに保存
tdsl build examples/china_with_import.tdsl --output out.json --pretty

# オフラインビルド（開発時に推奨）
tdsl build examples/china_with_import.tdsl --offline --pretty

# 複数ファイルをマージしてコンパイル
tdsl build part1.tdsl part2.tdsl --output merged.json --pretty

# IR の JSON Schema を標準出力（入力ファイル不要）
tdsl build --json-schema

# JSON Schema を整形してファイルに保存
tdsl build --json-schema --pretty --output timeline-ir.schema.json

check

.tdsl ファイルの構文エラーおよび意味エラー（lane 未定義参照、date 範囲矛盾など）を確認します。エラーがなければ終了コード 0 を返します。

tdsl check [OPTIONS] <FILE>...

引数

引数	説明
<FILE>...	入力 .tdsl ファイル、またはディレクトリ（配下の *.tdsl を再帰的に探索）。複数指定可（v2.0.0〜）

オプション

オプション	説明	デフォルト
--offline	Wikidata 解決を行わないことを明示する（現時点では唯一の動作。付けても付けなくても挙動は同じ）	—
--format <FORMAT>	出力形式（text / json）。json は code / severity / line / message を含む機械可読な診断を出す（v2.0.0〜）	text
--deny-warnings	警告が 1 件でもあれば非ゼロ終了する。既定では警告のみなら成功（v2.0.0〜）	—

診断コード（W204 など）の一覧は エラー一覧 を参照してください。text 出力ではコードと行番号が Warning [W204] line 2: ... の形式で前置されます（v2.0.0〜）。

複数ファイル・ディレクトリ指定時の挙動は lint / fmt と共通です（v2.0.0〜）。

• ディレクトリを渡すと配下の *.tdsl を再帰的に処理します
• 1 件でも失敗すれば非ゼロ終了しますが、最初の失敗で打ち切らず全件処理してから N of M file(s) failed: ... の要約を出します
• 対象が 2 件以上のときは === <path> === の見出しを付けます（単一ファイル指定時の出力は従来どおり）
• 処理順はパス名でソートします
• 対象が 0 件ならエラーになります（パスの打ち間違いを「問題なし」として通しません）

実行例

# 構文・意味チェック
tdsl check examples/china_dynasties.tdsl

# CI で使う（エラー時に非ゼロの終了コードを返す）
tdsl check my_timeline.tdsl && echo "OK"

# ディレクトリを再帰的にチェック
tdsl check examples

# 複数ファイルを指定
tdsl check a.tdsl b.tdsl

# 警告もゼロにしたい場合（CI 向け）
tdsl check my_timeline.tdsl --deny-warnings

# CI 向けに JSON 出力
tdsl check my_timeline.tdsl --format json

ast

.tdsl ファイルをパースして AST（抽象構文木）を標準出力にダンプします。文法デバッグに使うコマンドで、通常の利用フローでは使いません。

tdsl ast [OPTIONS] <FILE>

引数

引数	説明
<FILE>	入力 .tdsl ファイルのパス

実行例

# AST をダンプ
tdsl ast examples/china_dynasties.tdsl

# ページャで確認
tdsl ast examples/china_with_import.tdsl | less

merge

複数の .tdsl ファイルを読み込み、統合した IR JSON を出力します。最初のファイルのメタ情報（タイトル・単位・範囲）が優先されます。

tdsl merge [OPTIONS] <FILE> <FILE>...

引数

引数	説明
<FILE> <FILE>...	入力 .tdsl ファイルのパス（2 ファイル以上必須、順番にマージ）

オプション

オプション	説明	デフォルト
-o, --output <OUTPUT>	出力 JSON ファイルのパス	標準出力
--pretty	JSON を整形出力する	—
--offline	Wikidata フェッチをスキップし、静的アイテムのみ処理する	—
--no-cache	ローカルキャッシュをバイパスして API を直接呼び出す	—
--cache-ttl <CACHE_TTL>	キャッシュ有効期限（秒）。0 で無効化	86400（24時間）

実行例

# 2 ファイルをマージして整形出力
tdsl merge china_dynasties.tdsl world_wars.tdsl --pretty

# ファイルに保存
tdsl merge base.tdsl extension.tdsl --output combined.json --pretty

decompile

JSON IR ファイルを .tdsl ソースコードに逆変換します。JSON を他ツールで生成した場合や、IR からソースを復元したい場合に使います。start / end / time の秒精度・UTCオフセット（Z / ±HH:MM）も欠落なくラウンドトリップします（v1.27.0〜。それ以前は無声で破棄されていました）。

tdsl decompile [OPTIONS] [INPUT]

引数

引数	説明
[INPUT]	入力 JSON ファイルのパス（省略時は標準入力）

オプション

オプション	説明	デフォルト
-o, --output <OUTPUT>	出力 .tdsl ファイルのパス	標準出力

実行例

# JSON IR を .tdsl に逆変換
tdsl decompile out.json

# ファイルに保存
tdsl decompile out.json --output recovered.tdsl

# パイプライン経由（標準入力から）
tdsl build examples/china_dynasties.tdsl --pretty | tdsl decompile --output recovered.tdsl

制約（コメント非対応）: decompile は JSON IR を起点とするため、元の .tdsl に書かれていたコメント（//・/* */）は復元できません。IR にはコメント情報が含まれないため、これは IR を単一の真実とする設計上の恒久的な制約です。

fmt

.tdsl ファイルを正準スタイル（2 スペースインデント・ブロック間空行 1 行）に整形します。デフォルトでは整形結果を標準出力へ出力します。--write でファイルを直接上書きし、--check で差分があれば非ゼロ終了します（CI 向け）。--check と --write は同時に指定できません。

コメント（//・/* */）は保持されます。トップレベルの先頭・末尾コメントは位置を保ち、ブロック内部コメントは内容を保持したまま正準位置へ移動される場合があります。

tdsl fmt [OPTIONS] <FILE>...

引数

引数	説明
<FILE>...	入力 .tdsl ファイル、またはディレクトリ（配下の *.tdsl を再帰的に探索）。複数指定可（v2.0.0〜）。複数ファイル・ディレクトリ指定時の挙動は check と共通

オプション

オプション	説明	デフォルト
--check	フォーマットが必要な場合に非ゼロ終了する（ファイルは変更しない）。CI 向け	—
--write	整形結果でファイルを上書きする	—

実行例

# 整形結果を標準出力に表示
tdsl fmt examples/china_dynasties.tdsl

# ファイルを上書き
tdsl fmt examples/china_dynasties.tdsl --write

# CI でフォーマット差分チェック（差分があれば exit 1）
tdsl fmt examples/china_dynasties.tdsl --check

# ディレクトリを再帰的にチェック
tdsl fmt examples --check

lint

.tdsl ファイルの品質チェックを実施し、自動修正可能な問題を --fix で修正します。

tdsl lint [OPTIONS] <FILE>...

引数

引数	説明
<FILE>...	入力 .tdsl ファイル、またはディレクトリ（配下の *.tdsl を再帰的に探索）。複数指定可（v2.0.0〜）。複数ファイル・ディレクトリ指定時の挙動は check と共通

オプション

オプション	説明	デフォルト
--fix	安全な修正をファイルに直接適用する	—
--format <FORMAT>	出力フォーマット（text / json）	text

実行例

# リントチェックのみ
tdsl lint examples/china_dynasties.tdsl

# 自動修正を適用
tdsl lint examples/china_dynasties.tdsl --fix

# CI 向けに JSON 出力
tdsl lint examples/china_dynasties.tdsl --format json

# ディレクトリを再帰的にチェック
tdsl lint examples

fetch

Wikidata エンティティ（QID 指定）のラベル・説明・プロパティを取得して表示します。import ブロックを書く前に、対象エンティティのデータを確認する用途で使います。

tdsl fetch [OPTIONS] <QID>

引数

引数	説明
<QID>	Wikidata QID（例: Q7209）

オプション

オプション	説明	デフォルト
-l, --lang <LANG>	ラベルを取得する言語（カンマ区切り）	ja,en

実行例

# 漢（前漢）の情報を取得
tdsl fetch Q7209

# 英語・フランス語ラベルで取得
tdsl fetch Q7209 --lang en,fr

search

キーワードで Wikidata エンティティを検索し、候補 QID の一覧を表示します。import に使う QID を探す際に利用します。

tdsl search [OPTIONS] <QUERY>

引数

引数	説明
<QUERY>	検索クエリ（例: "漢王朝"）

オプション

オプション	説明	デフォルト
-l, --lang <LANG>	Wikidata 検索に使う言語	ja
-n, --limit <LIMIT>	最大取得件数（1〜50）	10
--json	JSON 形式で出力する	—

実行例

# 日本語で「漢王朝」を検索
tdsl search "漢王朝"

# 英語で検索し件数を増やす
tdsl search "Han dynasty" --lang en --limit 20

# JSON で取得してスクリプトに渡す
tdsl search "samurai" --json | jq '.[] | .id'

inspect

Wikidata エンティティを詳細解析し、年表へのマッピング戦略（どのプロパティを start / end に使うか等）を提案します。scaffold 実行前の事前調査に有効です。

tdsl inspect [OPTIONS] <QID>

引数

引数	説明
<QID>	Wikidata QID（例: Q7209）

オプション

オプション	説明	デフォルト
-l, --lang <LANG>	ラベル取得のフォールバック言語（カンマ区切り）	ja,en
--json	JSON 形式で出力する	—

実行例

# 徳川家康のエンティティを解析
tdsl inspect Q7243

# JSON で出力してスクリプト処理
tdsl inspect Q7243 --json | jq '.suggestions'

resolve

Wikipedia 記事の URL を Wikidata QID に変換します。記事を見つけたが QID が不明な場合に使います。

tdsl resolve [OPTIONS] <URL>

引数

引数	説明
<URL>	Wikipedia 記事の URL

オプション

オプション	説明	デフォルト
-l, --lang <LANG>	ラベル取得のフォールバック言語（カンマ区切り）	ja,en
--json	JSON 形式で出力する	—

実行例

# 記事 URL から QID を取得
tdsl resolve "https://ja.wikipedia.org/wiki/%E6%BC%A2"

# JSON で出力
tdsl resolve "https://en.wikipedia.org/wiki/Han_dynasty" --json

scaffold

Wikidata エンティティから .tdsl テンプレートを自動生成します。サブコマンド wikidata を指定します。

tdsl scaffold wikidata [OPTIONS] --qids <QIDS> --timeline <TIMELINE>

scaffold wikidata オプション

オプション	説明	デフォルト
--qids <QIDS>	カンマ区切りの QID リスト（例: Q7183,Q7209）【必須】	—
--timeline <TIMELINE>	年表の表示タイトル【必須】	—
-o, --output <OUTPUT>	出力 .tdsl ファイルのパス	標準出力
-l, --lang <LANG>	ラベル取得のフォールバック言語（カンマ区切り）	ja,en
--target <TARGET>	マッピングターゲット戦略（auto / span / event / event-range）	auto
--lane-mode <LANE_MODE>	レーン割り当て戦略（single / per-entity / by-kind）	per-entity
--single-lane-label <LABEL>	--lane-mode single 時の共有レーン名	項目

実行例

# 前漢・後漢を自動マッピングでスキャフォールド（Wikidata 連携）
tdsl scaffold wikidata \
  --qids "Q7209,Q8209" \
  --timeline "漢王朝年表" \
  --output han_dynasties.tdsl

# 全エンティティを単一レーンにまとめる
tdsl scaffold wikidata \
  --qids "Q7209,Q8209" \
  --timeline "漢王朝年表" \
  --lane-mode single \
  --single-lane-label "王朝"

# span として強制マッピング
tdsl scaffold wikidata \
  --qids "Q7183,Q7209,Q8209" \
  --timeline "漢・新・後漢" \
  --target span

render

.tdsl ファイルをスタンドアロンな HTML / SVG / PNG / PDF 年表にレンダリングします。基本的な使い方は Commands を参照してください。

tdsl render [OPTIONS] <FILE>

引数

引数	説明
<FILE>	入力 .tdsl ファイルのパス

オプション一覧

--format / --dpi / --png-scale / --orientation / --grid / --show-event-labels / --lane-height / --layout-style / --show-legend / --watch / --show-table の使い方は Commands を参照してください。--theme / --custom-css は スタイルカスタマイズ を参照してください。

オプション	値	デフォルト	導入バージョン	詳細
-o, --output <OUTPUT>	出力ファイルのパス	標準出力	—	—
--format <FORMAT>	html / svg / png / pdf	html	—（png/pdfはv1.10.0/v1.11.0〜）	Commands
--scale <SCALE>	横軸の 1 年あたりピクセル数	2	—	下記
--lane-height <LANE_HEIGHT>	各レーンの高さ（px）	60	—	Commands
--left-gutter <LEFT_GUTTER>	レーンラベル用の左ガター幅	120	—	下記
--top-margin <TOP_MARGIN>	時間軸のトップマージン	40	—	下記
--theme <THEME>	default / dark / print / pastel	default	—	スタイルカスタマイズ
--custom-css <CUSTOM_CSS>	テーマ CSS の後に注入するカスタム CSS ファイルのパス	—	—	スタイルカスタマイズ
--dpi <DPI>	PNG 出力の解像度（--png-scale と排他）	96	—	Commands
--png-scale <PNG_SCALE>	PNG 出力の固定ピクセル倍率（--dpi と排他）	—	—	Commands
--interactive	ズーム・パン・検索・凡例・詳細パネルを有効化	—	v1.1.0〜	下記
--color-map <COLOR_MAP>	タグ→色マッピング（例: war=#cc0000,dynasty=#3366cc）	—	v1.1.0〜	下記
--orientation <ORIENTATION>	horizontal / vertical	horizontal	v1.13.0〜	Commands
--grid <GRID>	none / decade / year / month	none	v1.14.0〜	Commands
--layout-style <LAYOUT_STYLE>	timeline / group-bands / gantt / zigzag	timeline	—	Commands
--watch	変更検出のたびに自動再レンダリング（html/svgのみ）	—	—	Commands
--show-table	内容一覧の表を追加する	—	—	Commands
--show-event-labels	イベントのドット・バー近傍にラベルを常時描画	—	—	Commands
--pdf-size <SIZE>	a4 / a3 / letter（--format pdf のみ）	a4	v1.17.0〜	下記
--pdf-landscape	PDF を横向きで出力（--format pdf のみ）	—	v1.17.0〜	下記
--pdf-margin <MM>	PDF の用紙マージン（mm、--format pdf のみ）	10	v1.17.0〜	下記
--pdf-title <TITLE>	PDF ドキュメントの Title メタデータ上書き（--format pdf のみ）	年表タイトル	v1.17.0〜	下記
--pdf-pagination	アイテムテーブルを複数ページに分割（--show-table 必須、--format pdf のみ）	無効（単一ページ）	v1.27.0〜	下記
--chart-pagination <N>	チャート本体を lane グループ単位で N レーンずつ複数ページに分割（--output 必須、--format svg/pdf のみ）	無効（単一ページ）	v1.28.0〜	下記
--chart-pagination-range <N>	チャート本体を時間範囲軸で N ページに分割（--output 必須、--chart-pagination と排他、--format svg/pdf のみ）	無効（単一ページ）	v2.0.0〜	下記

--scale / --left-gutter / --top-margin

タイムライン本体のレイアウト寸法を調整します。--scale は横軸方向の密度（大きいほど 1 年あたりの幅が広がる）、--left-gutter はレーンラベル列の幅、--top-margin は時間軸目盛りの上部余白です。長いレーンラベルが折り返される場合は --left-gutter を広げます。

# 1年あたり4pxに拡大し、長いレーンラベル用にガターを広げる
tdsl render examples/china_dynasties.tdsl --scale 4 --left-gutter 160 --output china_wide.html

--interactive

ズーム・パン・アイテム検索・凡例・詳細パネルを搭載したインタラクティブ HTML を生成します。--format html でのみ意味を持ちます（v1.1.0〜）。

凡例パネルには lane トグルに加えて、color_map（timeline ブロック内の宣言、または --color-map での上書き）に登録されたタグごとのチェックボックスが「タグ」セクションとして表示されます（v2.0.0〜、初期状態は全タグチェック済み）。タグ絞り込みは OR セマンティクスで動作し、チェックされたタグを1つも持たない item が非表示になります。すべてのチェックを外すとタグ絞り込み自体が無効化され、全 item が表示に戻ります。lane トグルとタグトグルは AND で合成されるため、両方の条件を満たす item だけが表示されます。color_map が未設定の場合、タグセクションは描画されません。

tdsl render examples/china_dynasties.tdsl --interactive --output china_interactive.html

--color-map

timeline ブロック内の color_map 宣言を CLI 側から上書きする、タグ→色マッピングです（v1.1.0〜）。カンマ区切りで タグ=色コード を列挙します。

tdsl render examples/china_dynasties.tdsl \
  --color-map "dynasty=#4b7bec,war=#e74c3c" \
  --output china.html

--pdf-size / --pdf-landscape / --pdf-margin / --pdf-title / --pdf-pagination

--pdf-size / --pdf-landscape / --pdf-margin / --pdf-title は --format pdf のときのみ有効な、用紙サイズ・向き・マージン・メタデータタイトルの指定オプションです（v1.17.0〜）。

# A3 横向き・マージン 15mm・タイトル指定で PDF を出力
tdsl render examples/china_dynasties.tdsl \
  --format pdf --pdf-size a3 --pdf-landscape --pdf-margin 15 --pdf-title "中国王朝年表" \
  --output china_a3.pdf

--pdf-pagination は --show-table と併用したときのみ有効で、アイテムテーブルを用紙サイズ・マージンに収まる行数ごとに複数ページへ分割します（v1.27.0〜）。1 ページ目はタイムライン本体（縮小描画）のみで、2 ページ目以降にテーブルが分割描画されます。--show-table を指定せずに --pdf-pagination のみ指定するとエラーになります。

tdsl render examples/china_dynasties.tdsl \
  --format pdf --show-table --pdf-pagination \
  --output china_paginated.pdf

--chart-pagination

--chart-pagination <N> はチャート本体（タイムライン部分）を lane グループ単位で複数ページに分割します（v1.28.0〜）。lane は (order, id) の順に並べ替えたうえで N レーンずつチャンク化されます。時間軸（meta.range）は全ページ共通で、各アイテムは必ず 1 つの lane に属するため、span / event_range がページ境界でクリップされることはありません。

--format svg の場合、<stem>.pageN.<ext> という命名で複数ファイルに出力されます（N は総ページ数の桁数に合わせて 0 埋め）。--show-table を併用すると、チャートページ群の後ろに IR 全体の内容一覧を載せた専用テーブルページを 1 枚追加します（このページのフッタは 1 / 1 固定で、テーブル自体の複数ページ分割は SVG では未対応です）。

--format pdf の場合は別ファイルに分割されず、単一 PDF ファイル内に「チャートページ群（lane グループ順）→ テーブルページ群」の順で複数ページとして出力されます。--show-table のみを指定した場合は IR 全体を 1 枚の未分割テーブルページとして末尾に追加し、--pdf-pagination を併用した場合は既存の行分割ロジックでテーブルページ群を生成します。いずれの場合もテーブルページのフッタはテーブルページ数のみを数え、先行するチャートページ数は含めません。

--show-legend は各チャートページに個別描画されるため、ページごとに凡例の内容が異なり得ます（そのページの lane・アイテムに対応した凡例が描画される、意図した挙動です）。

--output の指定が必須で（stdout は複数ファイル・複数ページを表現できないため）、--watch との併用はできません。lane の group がページ境界をまたいで分断される場合は stderr に警告が出ますが、出力自体は生成されます（詳細は トラブルシューティング を参照）。Playground はブラウザ内 WASM で完結しており tdsl-render のページ分割ロジックは公開していないため、--chart-pagination の挙動は Playground では再現できません。試すには CLI（tdsl render）を使用してください。

# タイムライン本体を lane グループ単位で複数の SVG ページに分割
# china.page1.svg / china.page2.svg ... が生成される
tdsl render examples/china_dynasties.tdsl --format svg --chart-pagination 2 --output china.svg

# タイムライン本体を lane グループ単位で複数の PDF ページに分割
# 単一の china_chart.pdf 内に複数ページとして出力される（テーブルなし）
tdsl render examples/china_dynasties.tdsl --format pdf --chart-pagination 2 --output china_chart.pdf

# チャートページ分割 + テーブルページ分割を併用（チャートページ群 → テーブルページ群の順）
tdsl render examples/china_dynasties.tdsl \
  --format pdf --chart-pagination 2 --show-table --pdf-pagination \
  --output china_full_paginated.pdf

--chart-pagination-range

--chart-pagination-range <N> はチャート本体（タイムライン部分）を lane グループ軸ではなく時間範囲軸で複数ページに分割します（v2.0.0〜）。meta.range を N 個の連続する非空の整数年区間に均等分割し、区間ごとに 1 ページを描画します。lane グループ軸分割とは異なり各ページの TimelineIr は全 lane / item を保持したまま meta.range のみが書き換わるため、区間境界をまたぐ span / event_range は既存のクランプ処理でクリップされ、クリップされた辺に継続マーカー（role="img" の三角形グリフ、横書き/縦書き両対応）が描画されます。境界をまたぐ item がある場合は --chart-pagination の lane 境界警告と同様に stderr にも警告が出力されます。

--chart-pagination とは相互排他です（同時指定はエラー）。lane グループ軸ではなく時間範囲軸で分割したい場合にこちらを使います。--format svg（<stem>.pageN.svg の複数ファイル）・--format pdf（単一 PDF 内の複数ページ）の両方に対応し、ページ構成規則（--show-table / --pdf-pagination との組み合わせ時のテーブルページ配置・フッタのページ数カウント）は --chart-pagination と共通です。--output の指定が必須で、--watch との併用はできません。Playground では tdsl-render のページ分割ロジックを再現できないため、試すには CLI（tdsl render）を使用してください。

# タイムライン本体を時間範囲軸で複数の SVG ページに分割
# china.page1.svg / china.page2.svg ... が生成される
tdsl render examples/china_dynasties.tdsl --format svg --chart-pagination-range 2 --output china.svg

# タイムライン本体を時間範囲軸で複数の PDF ページに分割
# 単一の china_chart.pdf 内に複数ページとして出力される（テーブルなし）
tdsl render examples/china_dynasties.tdsl --format pdf --chart-pagination-range 2 --output china_chart.pdf

init

手動編集用の最小 .tdsl テンプレートを生成します。Wikidata 接続は不要です。

tdsl init [OPTIONS]

オプション

オプション	説明	デフォルト
-o, --output <OUTPUT>	出力 .tdsl ファイルのパス	標準出力
--timeline <TIMELINE>	年表の表示タイトル	新しい年表
--range-start <RANGE_START>	範囲開始年	0
--range-end <RANGE_END>	範囲終了年	2000
--lanes <LANES>	レーンラベル（カンマ区切り、例: "王朝,事件,人物"）	""

実行例

# 最小テンプレートを生成（標準出力）
tdsl init

# ファイルに保存してレーンを指定
tdsl init \
  --output my_timeline.tdsl \
  --timeline "架空世界年表" \
  --range-start 1000 \
  --range-end 1500 \
  --lanes "王国,事件,人物"

import-csv

CSV ファイルから年表アイテムを読み込み、.tdsl スニペットに変換します。CSV の列仕様（ヘッダー行・時刻リテラル・source / origin 列）は Commands を参照してください。

tdsl import-csv [OPTIONS] <CSV>

引数

引数	説明
<CSV>	入力 CSV ファイルのパス（UTF-8、ヘッダー行あり）

オプション

オプション	説明	デフォルト
-o, --output <OUTPUT>	出力 .tdsl スニペットのパス	標準出力
--append <APPEND>	生成アイテムを既存 .tdsl ファイルに追記	—

実行例

# CSV を .tdsl スニペットに変換（標準出力）
tdsl import-csv items.csv

# ファイルに保存
tdsl import-csv items.csv --output items_snippet.tdsl

# 既存ファイルに追記
tdsl import-csv new_items.csv --append my_timeline.tdsl

export-csv

IR を CSV に書き出します。import-csv と対称な往復（ラウンドトリップ）を目的とし、CSV の列仕様は Commands を参照してください。

tdsl export-csv [OPTIONS] <FILE>

引数

引数	説明
<FILE>	入力ファイル。.tdsl ソース（lowering して IR 化）または .json（IR を直接読み込み）

オプション

オプション	説明	デフォルト
-o, --output <OUTPUT>	出力 CSV ファイルのパス	標準出力
--offline	Wikidata 取得をスキップする（静的アイテムのみ）。.json 入力では無視される	false
--no-cache	ローカルキャッシュをバイパスして再取得する	false
--cache-ttl <SECONDS>	キャッシュ TTL（秒）。0 で無効化	86400

実行例

# .tdsl を CSV に書き出し（標準出力、静的のみ）
tdsl export-csv my_timeline.tdsl --offline

# ファイルに保存
tdsl export-csv my_timeline.tdsl --offline --output items.csv

# IR JSON から書き出し
tdsl build my_timeline.tdsl --offline --output ir.json
tdsl export-csv ir.json --output items.csv

cache

Wikidata 取得結果のローカルキャッシュを管理します。サブコマンド status または clear を指定します。

tdsl cache <COMMAND>

cache status

キャッシュの統計情報（ファイル数・合計サイズ・最古／最新エントリ）を表示します。

tdsl cache status

cache clear

キャッシュエントリを削除します。

tdsl cache clear [OPTIONS]

オプション	説明	デフォルト
--older-than <DAYS>	指定日数より古いエントリのみ削除	—（全件削除）

実行例

# キャッシュ統計を表示
tdsl cache status

# 全キャッシュを削除
tdsl cache clear

# 7 日より古いキャッシュを削除
tdsl cache clear --older-than 7

completions

指定シェル向けの補完スクリプトを生成します。生成したスクリプトをシェルの設定ファイルに追加することで、tdsl のサブコマンドやオプションを Tab 補完できるようになります。

tdsl completions [OPTIONS] <SHELL>

引数

引数	説明
<SHELL>	対象シェル（bash / elvish / fish / powershell / zsh）

実行例

# bash 補完スクリプトを生成・インストール
tdsl completions bash >> ~/.bashrc
source ~/.bashrc

# fish 補完スクリプトをインストール
tdsl completions fish > ~/.config/fish/completions/tdsl.fish

# zsh 補完スクリプトをインストール
tdsl completions zsh > ~/.zfunc/_tdsl
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
source ~/.zshrc

lsp

LSP（Language Server Protocol）サーバを stdio 経由で起動します。標準入力から JSON-RPC 2.0 メッセージを読み込み、標準出力に応答を書き出します。

tdsl lsp

対応機能

機能	説明
textDocument/publishDiagnostics	パースエラー・検証警告・静的参照エラーをリアルタイムで通知
textDocument/didOpen	ドキュメントを開いたときに診断を実行
textDocument/didChange	ドキュメント変更時に診断を再実行（FULL sync）
textDocument/didClose	ドキュメントを閉じたときに診断をクリア
textDocument/completion	DSL キーワード補完候補を返す（文脈非依存・全キーワード）
textDocument/hover	lane ID → lane 情報 / QID → キャッシュ済みエンティティ情報（offline）/ 時刻リテラル → 精度・offset 情報（v1.27.0〜）
textDocument/definition	lane 参照位置 → lane 宣言位置へのジャンプ
textDocument/codeAction	tdsl lint --fix 相当の自動修正を quick fix として提示（全文置換・offline）
textDocument/documentSymbol	timeline / lane / アイテムの階層シンボルを返す
textDocument/references	lane ID の全参照位置を返す（includeDeclaration で宣言含む／含まないを制御）
textDocument/rename	lane ID の宣言＋全参照を新名称に一括置換（明示的 as <alias> 限定）
textDocument/prepareRename	リネーム対象の妥当性検証（as 省略 lane は拒否）
textDocument/formatting	DSL ソースを正準形に整形する全文置換 TextEdit を返す

import / map / apply ブロックはネットワークアクセスを伴わない静的解析（offline）で診断されるため、Wikidata 取得が前提のエンティティ解決は行われません。エディタ設定（VS Code / Neovim / Helix）と各機能の詳しい使い方は インストール を参照してください。

実行例

# LSP サーバを起動（stdin 待機でブロックする）
tdsl lsp

# 最小 JSON-RPC リクエストで動作確認（Content-Length ヘッダ必須）
echo -e 'Content-Length: 2\r\n\r\n{}' | tdsl lsp

関連ドキュメント

• Commands — 基本フローの入口
• 文法 — 文法の詳細
• エラーコードリファレンス — 診断コードの一覧