Skip to content

Usage

All commands take a --file/-f option to select the timeline file (default: .research-timeline.json in the current directory).

init — create a new timeline

research-timeline init \
  --name "PASM DTC Discovery" \
  --desc "Observation of Classical Prethermal DTC on IBM Heron" \
  --domain quantum \
  --author "N47Lab" \
  --affiliation independent \
  --ai-role cognitive_prosthesis \
  --output timeline.json
Option Required Description
--name, -n yes Project name
--desc, -d yes Project description
--domain no Research domain (default quantum)
--author, -a yes Author name
--affiliation no Affiliation (default independent)
--orcid no ORCID URL
--background no Academic background (default without academic degrees)
--ai-role no AI role: cognitive_prosthesis, co_pilot, autonomous_agent (default cognitive_prosthesis)
--output, -o no Output file (default .research-timeline.json)

log — add a typed event

research-timeline log T1 \
  --type T1 \
  --date 2026-07-31 \
  --desc "First commit: 14 QPU experiments, Z>50sigma" \
  --z-combined 50.0 \
  --git-commit c3ddc4a \
  --job-ids marrakesh-pasm-1 \
  --tags commit,qpu \
  --file timeline.json

Valid event IDs: T0, T1, …, Tn, pivot, control, submission, publication, milestone. Duplicate IDs are rejected.

Option Required Description
event_id yes (positional) Event ID, must match a valid typed phase
--type yes Event type (free text, usually same as ID)
--date no Event date YYYY-MM-DD (default: today)
--desc yes Event description
--tags no Comma-separated tags
--z-score no Z-score metric
--shots no Shots metric
--backend no Quantum backend metric
--job-ids no Comma-separated IBM Quantum job IDs (evidence)
--z-combined no Combined Z-score metric
--git-commit no Git commit hash (evidence)
--data-links no Comma-separated data repository links (evidence)
--code-links no Comma-separated code repository links (evidence)
--file, -f no Timeline file (default .research-timeline.json)

edit — edit an existing event

research-timeline edit T1 --desc "Updated description" --tags revised --file timeline.json

Only the fields you pass are changed; the document is validated against the schema before it is written.

Option Description
--desc New description
--date New date (YYYY-MM-DD)
--end-date New end date (YYYY-MM-DD)
--tags New tags (comma-separated)
--file, -f Timeline file

remove — remove an event

research-timeline remove T1 --yes --file timeline.json

Asks for confirmation unless --yes is passed.

list — display events

research-timeline list --metrics --file timeline.json
Option Description
--metrics, -m Also show metrics
--type Filter by event type
--tag Filter by tag (exact match)
--since Only events with date >= YYYY-MM-DD
--until Only events with date <= YYYY-MM-DD
--json Output the filtered events as JSON
--file, -f Timeline file

export — export to papers/reports/web

research-timeline export --format latex -o timeline.tex --file timeline.json
research-timeline export --format markdown -o timeline.md --file timeline.json
research-timeline export --format html -o timeline.html --file timeline.json
research-timeline export --format jsonld -o timeline.jsonld --file timeline.json
research-timeline export --format csv -o timeline.csv --file timeline.json
research-timeline export --format gantt -o timeline_gantt.tex --file timeline.json
research-timeline export --format prov -o timeline_prov.jsonld --file timeline.json
Option Description
--format latex, markdown, html, jsonld, csv, gantt, prov (default latex)
--output, -o Output file (default: print to stdout)
--file, -f Timeline file
  • LaTeX — a table environment ready for manuscripts and reports
  • Markdown — a portable table for READMEs
  • HTML — a standalone widget (no build step)
  • JSON-LD — schema.org ResearchProject metadata for archives and repositories
  • CSV — machine-readable, spreadsheet-friendly rows
  • Gantt — publication-ready LaTeX TikZ chart (supports --end-date ranges)
  • PROV — W3C PROV-O provenance graph (JSON-LD): project → Bundle, events → Activity, evidence → Entity, author → Person, AI role → SoftwareAgent

validate — check a timeline against the schema

research-timeline validate --file timeline.json

Validates against the shipped JSON Schema (draft-07), including ISO-date checks. Prints [OK] Timeline is valid! on success, or a list of errors with exit code 1 (CI-friendly).

stats — summary statistics

research-timeline stats --file timeline.json

Prints the event count, the date window, and per-type / per-tag counts. Pass --json for machine-readable output.