ingest

Import tasks from any external source into your markdown vault via a JSONL file.

md2do ingest <file.jsonl> [options]

Overview

md2do ingest reads a JSONL file (one task record per line), converts each record into a markdown task line with full metadata, and writes the result to your vault as a regenerated markdown file.

This is the recommended way to bring in tasks from sources that don't have a native md2do integration — Teams mentions, Outlook flagged emails, Slack saved messages, calendar items, or any other system an MCP agent can read.

Vault files are read-only

Files generated by ingest are fully regenerated on every run. Don't hand-edit them — edit tasks in your regular markdown notes instead.

Options

Option	Description
<file.jsonl>	Path to the JSONL input file
-o, --output <path>	Write output to a specific file (overrides --vault derivation)
--vault <root>	Vault root directory (default: current directory)
--dry-run	Print generated markdown to stdout without writing any file

Output Path

By default, output is written to <vault>/<source>/<basename>.md:

vault/
  todoist/
    inbox.md         # md2do ingest todoist-inbox.jsonl --vault vault
  teams/
    mentions.md      # md2do ingest teams-mentions.jsonl --vault vault
  outlook/
    flagged.md       # md2do ingest outlook-flagged.jsonl --vault vault

Use --output to override:

md2do ingest my-tasks.jsonl --output notes/imported.md

JSONL Format

Each line in the input file is a JSON object representing one task:

{"source":"teams","externalId":"msg-789","text":"Follow up on PR review","completed":false,"priority":"normal","tags":["eng"]}
{"source":"teams","externalId":"msg-790","text":"Update onboarding doc","completed":false,"priority":"high","dueDate":"2026-08-10","assignee":"nick"}
{"source":"teams","externalId":"msg-100","text":"Old action item","completed":true}

Required Fields

Field	Type	Description
source	string	Source slug (e.g. teams, outlook, slack). Used in {source:ID} markers and output path.
externalId	string	Unique ID in the source system.
text	string	Task description.
completed	boolean	Whether the task is done.

Optional Fields

Field	Type	Description
priority	string	urgent, high, normal, or low
dueDate	string	Due date in YYYY-MM-DD format
tags	string[]	Array of tag names (without #)
assignee	string	Username (without @)
metadata	object	Arbitrary extra data — ignored by md2do but preserved for reference

Generated Markdown

Given this JSONL:

{"source":"outlook","externalId":"AAMk-abc","text":"Review Q3 budget","completed":false,"priority":"high","dueDate":"2026-08-10","tags":["finance"],"assignee":"nick"}
{"source":"outlook","externalId":"AAMk-def","text":"Reply to procurement","completed":true}

md2do ingest outlook-flagged.jsonl --vault vault --dry-run produces:

# Outlook

- [ ] Review Q3 budget @nick !! #finance #due/2026-08-10 {outlook:AAMk-abc}

## Completed

- [x] Reply to procurement {outlook:AAMk-def} {completed:2026-08-02}

The generated lines use all standard md2do metadata syntax:

• @assignee, priority markers, #tags, #due/DATE — fully parsed by md2do list
• {source:externalId} — source link, deduplicated by scanner
• {completed:DATE} — set to today's date on ingest

Examples

# Preview without writing
md2do ingest teams-mentions.jsonl --dry-run

# Write to vault
md2do ingest teams-mentions.jsonl --vault ~/notes

# Specify output file directly
md2do ingest slack-saved.jsonl --output ~/notes/slack/saved.md

# Ingest from a temporary file produced by an MCP agent
md2do ingest /tmp/outlook-flagged.jsonl --vault ~/obsidian-vault

Mixed Sources

If a JSONL file contains records from more than one source, md2do warns you and uses the first record's source slug for the output path derivation:

⚠️  Warning: Mixed sources detected: teams, outlook. Using first source "teams" for output path derivation.

Use separate JSONL files per source to avoid ambiguity.

Next Steps

• Multi-Source Ingestion Guide — conceptual overview and MCP agent workflow
• Task Format — how {slug:ID} source links work
• Todoist Integration — native two-way Todoist sync