Writes

These commands write to your workspace. Every lesson write embeds its sections inline, so retrieval is live the moment the command returns.

course create / course import / lesson add / lesson add-md write the lesson and index it for keyword + semantic search in one call.
flashcard add persists only; flashcards aren't part of retrieval.
note add persists immediately; note text appears in semantic search asynchronously.

Courses & lessons

Add a course from raw markdown with the same parsing as the GitHub crawl — just without the network fetch. lesson add treats one document as a single lesson (its H1 becomes the title); lesson add-md splits one document into many lessons using the single-README rule (H2 → module, H3 → lesson). Pass --base-url to rewrite relative image/link URLs to absolute, exactly as the crawl does.

course create

Create a new, empty course and print its id. A unique learnos://manual/<id> source URL is generated when --source-url is omitted.

Parameters

Name	Type	Default	Description
--title*	string	—	Course title (also accepted as a positional argument).
--source-url	string	—	Provenance URL (must be unique). Generated if omitted.
--format	json \| text	json	Output format. In text mode: `<course_id>\t<title>`.

Returns

The created course (course_id, source_url).

lesson add

Append ONE markdown document to a course as a single lesson. Content from --file or piped stdin.

Parameters

Name	Type	Default	Description
--course*	string	—	Target course id.
--title	string	—	Lesson title. Omit to use the document's H1.
--module	string	—	Optional module / section name.
--base-url	string	—	Base URL/dir to resolve relative links & images against.
--file	string	—	Path to a markdown file. If omitted, read from stdin.
--format	json \| text	json	Output format.

Returns

The course id plus the created lesson(s) (id + title). Searchable (keyword + semantic) immediately.

lesson add-md

Split ONE markdown document into MULTIPLE lessons (H2 → module, H3 → lesson) and append them all to a course.

Parameters

Name	Type	Default	Description
--course*	string	—	Target course id.
--base-url	string	—	Base URL/dir to resolve relative links & images against.
--file	string	—	Path to a markdown file. If omitted, read from stdin.
--format	json \| text	json	Output format.

Returns

The course id plus every created lesson (id + title).

CID=$(learnos course create --title "My Notes Course" --format text | cut -f1)
learnos lesson add --course "$CID" --module "Internals" --file ./architecture.md
learnos lesson add-md --course "$CID" --file ./CURRICULUM.md   # split into many

Import a local course folder

course import walks a local NN-module/NN-lesson/README.md directory tree on your machine (outer dir → module, inner dir → lesson, leading numbers → order) and uploads each lesson to your workspace. Each README's H1 becomes the lesson title (or the humanized folder name when the file is frontmatter-led). Links stay relative by default; pass a --base-url (e.g. a GitHub blob base) to rewrite them to absolute.

It is append-safe: a re-run of the same --dir resolves to the same course (via a deterministic learnos://local/<abs-dir> source URL) and refuses to mutate unless you choose --append or --replace.

course import

Walk a local NN-module/NN-lesson/README.md tree and import it as a course. Re-runs map to the same course and require --append or --replace.

Parameters

Name	Type	Default	Description
--dir*	string	—	Path to the course directory (contains NN-module/NN-lesson/README.md).
--title	string	—	Course title. Required only when creating a new course.
--base-url	string	—	Base URL to rewrite relative links/images against (e.g. a github blob base). Left relative if omitted.
--append	boolean	false	Course exists: append new lessons after the current max order (preserves existing lessons + study data).
--replace	boolean	false	Course exists: DESTRUCTIVE — delete all its lessons and re-insert. Cascades to notes, flashcards, highlights, and progress.
--format	json \| text	json	Output format.

Returns

The mode (created | appended | replaced), course_id, source_url, and lesson count. Searchable (keyword + semantic) immediately.

learnos course import --dir ./my-course --title "My Course"   # create
learnos course import --dir ./my-course --append             # add new lessons later
learnos course import --dir ./my-course --replace            # destructive re-import

Flashcards & notes

flashcard add

Create a flashcard (front question + back answer) on a lesson. Appears in the lesson's deck immediately.

Parameters

Name	Type	Default	Description
--lesson*	string	—	Lesson UUID the card belongs to.
--question*	string	—	Front / question.
--answer*	string	—	Back / answer.
--format	json \| text	json	Output format.

Returns

The created card's result (flashcard_id, lesson_id).

note add

Append a timestamped markdown note entry to a lesson. Content from --content or piped stdin.

Parameters

Name	Type	Default	Description
--lesson*	string	—	Lesson UUID the note belongs to.
--content	string	—	Markdown body. If omitted, read from stdin.
--format	json \| text	json	Output format.

Returns

The created note's result (note_id, lesson_id).

learnos flashcard add --lesson <id> --question "What is the call stack?" --answer "..."
echo "## Recap\n- closures capture scope" | learnos note add --lesson <id>

Writes

Courses & lessons

Import a local course folder

Flashcards & notes

On this page

Command Palette