Menu

Tooling reference

This page documents Org2 tooling workflows: agenda, formatter, roam, publish, and more.

The CLI here is the shared backend surface that powers editor integrations and AI automation. Most users should interact through their editor; direct CLI use is optional.

Core CLI commands

Run npm run org2 -- --help for exact current flags.

Major command families:

  • agenda

  • todo

  • plan

  • capture

  • archive, refile

  • fmt

  • id, query, backlinks

  • roam ...

  • crypt ...

  • export html

  • publish

  • lsp

Agenda

Purpose: query scheduled/deadline items from Org files.

Example:

npm run org2 -- agenda --dir ~/notes --recursive --from 2026-02-20 --to 2026-02-27

Notable capabilities:

  • Date windows: --today, --days, --from, --to

  • Status/kind filters: --status, --kind, --when

  • Time/date dimensions: weekday/week/month/quarter/year/date filters

  • Content filters: tags, TODO keyword, priority, effort, property, file match

  • Ordering and grouping: --sort, --group, --date-order

  • Output modes: --format text|json

Date semantics (planner wording)

To avoid ambiguity in scheduling UX and automation:

  • tomorrow: next calendar day.

  • next week: upcoming Monday (calendar-week boundary), not strictly +7 days.

  • in one week: exactly 7 days from today.

  • next month: first day of the next calendar month.

Agenda includes both SCHEDULED: and DEADLINE: items when those planning timestamps are in range.

TODO and planning edits

TODO transitions

npm run org2 -- todo toggle --file notes.org --line 42 --apply
npm run org2 -- todo set --file notes.org --line 42 --status in_progress --apply

Planning updates

npm run org2 -- plan set --file notes.org --line 42 --kind scheduled --date 2026-02-25 --apply

Formatter

Purpose: canonical formatting for Org2 files.

Examples:

npm run org2 -- fmt --dir ~/notes --recursive --check
npm run org2 -- fmt --dir ~/notes --recursive --apply

Useful flags:

  • --check (report-only)

  • --apply (write changes)

  • --file / --files

  • --file-match / --exclude-file

  • --config org2.json

Roam workflows

Org2 supports roam-style IDs, backlinks, node creation, and both Wiki-link and ID-link based navigation.

Ensure IDs exist

npm run org2 -- roam db-sync --dir ~/notes --recursive --apply
npm run org2 -- roam backlinks --id 123e4567-e89b-12d3-a456-426614174000 --dir ~/notes --recursive --format json

Create a node

npm run org2 -- roam node new --dir ~/notes --title "Acme Corp" --apply
npm run org2 -- roam link insert-backlink --file notes.org --pos 30:0 --title "Acme Corp" --apply

When Org2 sees an internal roam link:

  • [[id:UUID][desc]] resolves directly to that node ID.

  • [[Node Title]] resolves by title lookup in the roam index.

Backlinks include references from both forms.

When rendering backlink context lines, Org2 may strip embedded link markup and show human-readable context text.

If title collisions exist, prefer explicit ID links for deterministic targeting.

Org-crypt workflows

Purpose: encrypt and decrypt sensitive subtrees while staying in plain-text Org workflows.

Examples:

npm run org2 -- crypt decrypt --file notes.org2 --line 42 --passphrase 'your-passphrase' --apply
npm run org2 -- crypt encrypt --file notes.org2 --line 42 --passphrase 'your-passphrase' --apply

Current behavior:

  • Operates on the subtree at the provided cursor line.

  • Requires an explicit passphrase value for CLI calls.

  • :crypt: tags can be used by editor tooling to scope encrypted-note workflows.

  • Encrypt/decrypt behavior is supported now, with further hardening and ergonomics expected as alpha evolves.

Export and publish

HTML export

npm run org2 -- export html --file README.org --out README.html --apply
npm run org2 -- export html --dir docs/site --recursive --out-dir site --apply

Common options:

  • --toc, --toc-depth

  • --number-headings, --number-headings-depth

  • --css

  • --rewrite-file-links

Publish projects

Publish projects are defined in org2.json under publish.projects.

Example:

npm run org2 -- publish docs-site --config org2.json

This docs site itself is generated this way.

IDs, query, backlinks

  • id get/ensure: read or create IDs

  • query --id: locate node definitions

  • backlinks --id: find all references

LSP

Start language server:

npm run org2 -- lsp

Current focus is VS Code integration in editors/vscode-org2/.

CI and Pages deployment

This repository includes a GitHub Actions workflow that:

  1. builds Org2,

  2. runs org2 publish docs-site,

  3. uploads site/ artifact,

  4. deploys to GitHub Pages on main.