Get familiar with your next project.

Installation

Requires Node.js 22.14 or newer. Install Git for source commit attribution. The npm package is @flashlearnai/cli, version 0.5.0; the executable is flashlearn.

npm install --global @flashlearnai/cli
flashlearn --help
flashlearn --version

From a source checkout:

npm ci
npm run build
npm run cli -- --help

The root development runner ensures sibling build outputs are ready and uses the repository root as cwd. Use --project to target another repository. For structured stdout, suppress npm's banner:

npm --silent run cli -- project status --project /path/to/repo -o json

Generate, then learn

flashlearn generate --project /path/to/repo
flashlearn start --project /path/to/repo

Open http://localhost:4173. Generation creates missing storage automatically, so a separate init is optional. The install includes the browser UI; no build is required for npm users.

Every command defaults to your current working directory. Use --project or -p for each invocation targeting another repository:

flashlearn project show --project /path/to/repo
flashlearn project status -p /path/to/repo -o json
flashlearn question list -p /path/to/repo -o yaml

If start finds no cards, a terminal asks whether to generate them first (default no), noting that a configured AI endpoint may be used. Non-interactive runs exit 1 with guidance. Use flashlearn start --project /path/to/repo --yes (or -y) to approve empty-deck generation. Existing decks are not regenerated; failed generation or a still-empty deck prevents startup.

Live study

The local UI uses GET /api/cards/next for server-selected due cards and GET /api/cards for deck counts. GET /api/project names the project the deck came from, when it declares one. Study what is due, or choose topics yourself: a topic session is dealt from the loaded deck and is an early review, not the due queue, because the next-card endpoint has no topic filter. Cards arrive as multiple choice or as recall, mixed by default, and Mixed, Multiple choice or Recall only forces one kind for the session. Answers come from the deck already loaded; GET /api/cards/:id fetches a card that became due after that load. Rate each card incorrect, hard, correct, or easy. A session allows up to 12 acknowledged reviews; incorrect cards can be due again immediately, and repeats count toward the cap.

Ratings post to POST /api/review. The UI shows Saving review… until confirmation, displays the server's due date, and waits for Next due card. Failed or malformed acknowledgements block advancement and new sessions and let you retry the same rating. A lost response may mean the save already succeeded; without an idempotency key, retrying can record the rating twice.

Saved schedules survive reloads; the transcript resets and the server selects due cards again rather than replaying future cards. No cards due (a 404 from the next-card endpoint) is distinct from an empty project.

Command reference

• review [directory]: review due cards in an interactive multiple-choice TUI. Choose an answer with 1–4 from shuffled deck answers; feedback reveals the correct answer and source and automatically saves correct/incorrect. Enter/Space continues after save; Q, Ctrl+C, or Ctrl+D quits. Up to 12 reviews are saved per session, including immediately due repeats, using the browser's learning schedule. At least two distinct, nonempty deck answers are required; run generate for an empty or insufficient deck. Interactive stdin/stderr are required; save failures stop the session with exit 1. No server or model calls are needed. Accepts a positional directory or --project.
• init [directory]: optional storage-only setup; preserve existing data.
• generate [directory]: initialize missing storage, extract, validate, and persist cards. Supports --subpath and --max-files.
• start [directory]: serve the local Teams-style review client and API. Supports --host, --port, and --yes/-y.
• project show: show this invocation's project directory.
• project status: show card and review counts.
• question list and question get <id>: inspect generated content.

All commands accept -p, --project <directory> before or after the command; relative paths resolve against cwd. Positional directories remain supported for init, generate, and start, but cannot be combined with --project. Repeated project flags are invalid.

Migration: FLASHLEARN_PROJECT and old saved user configuration are ignored and left untouched. project set has been removed and returns exit code 2 with migration guidance. init never selects a project for future commands.

Queries accept -o, --output text|json|yaml (default text). Project diagnostics and generation progress go to stderr, keeping query stdout parseable. Use project --help or question get --help for contextual help. Server defaults are localhost and port 4173; wildcard hosts 0.0.0.0 and :: are rejected. Exit codes: 0 success, 1 operation failure, 2 invalid arguments.

Scope a generation run

flashlearn generate --project /path/to/repo --subpath src --max-files 20

--subpath selects a repository-relative directory, not an individual file; absolute paths and .. segments are invalid. --max-files must be a positive safe integer and limits eligible files after ranking, not traversal or cards. Both flags belong to generate only. Defaults are the whole project with bounded AI/offline generation budgets. The project root and repository-relative attribution remain unchanged.

Generation reports new or updated cards and the total available for study. It upserts without pruning cards outside the scan. Zero generated cards can succeed if a previous deck remains; no available study cards means exit 1.

Local-first data boundaries

Cards, review metadata, and project settings are stored under .flashlearn/ in the repository. Keep generated content out of Git. No user-level project selection is read or written.

Generation begins with an INFERENCE SOURCE step offering Copilot, OpenAI, Claude, custom endpoint, or offline heuristic. Use generate --inference-source <name> to select explicitly. OpenAI and Claude accept masked, current-run-only API keys and a model; custom accepts a full HTTP(S) chat-completions URL, model, optional key and authentication header. URLs with embedded credentials are rejected. Blank required settings cancel to offline mode; invalid source names and URLs fail with guidance.

Without an explicit source flag, configured FLASHLEARN_ENDPOINT_URL and FLASHLEARN_ENDPOINT_MODEL take precedence; authentication uses optional FLASHLEARN_ENDPOINT_API_KEY. Noninteractive runs without configured inference use the offline heuristic. Supported source extensions are .go, .js, .jsx, .md, .ts, and .tsx.

Selected AI providers receive code/documentation. Prompted keys are never persisted. Offline heuristic cards extract complete definitions, explanations and code comments, skip procedural/media fragments, and have no LLM synthesis or categories. They send no code to an AI provider.

Try the static demo

Open the sample study session →

The Pages demo ships a curated, hand-authored deck about public FlashLearn source. Multiple-choice sessions balance selected topics across up to 12 cards, rotate the starting topic when topics outnumber slots, and advance each topic by cards actually dealt. It reads no local repository and makes no API requests. Ratings and topic/card cursors are session-only and reset on reload; it does not save a learning-engine schedule.

Daily-workflow integrations

Today you can review through a local Teams-style interface and use the CLI from repository workflows. Native Microsoft Teams, GitHub, and Slack delivery integrations are planned, not currently installed bots or apps. Repository ingestion is available today; wiki connectors are planned.

Help and updates

Report problems in GitHub Issues with CLI/Node versions and reproducible steps. Keep private code, decks, and credentials out of reports. See the release runbook for build and publishing instructions.

Understanding-first generation and progress

Generation shows six numbered stages on stderr: scan, selection, generation, quality review, categories and persistence. Indented details report batch starts/completions, active/failed/reused counts, elapsed/request times, remaining timeout, and category repair attempts. At most 100 new or updated cards are saved per run; existing cards are retained. Use flashlearn generate --copilot for automatic fast model routing, or --copilot-model <name> to choose a model. Both explicitly opt into Copilot and override endpoint environment configuration.

A local classification pass excludes dependency/license copies, agent tooling and tests, prioritizes README and design docs, then groups important code by subsystem. All AI providers synthesize focused questions from code and documentation in up to eight parallel four-file batches with bounded excerpts. Generation and categorization each allow 15 minutes per call with ongoing progress. Evidence quotes must match cited excerpts; ranking filters low-value and repetitive candidates. Documentation claims are labeled, including aspirational designs. Evidence matching cannot guarantee semantic accuracy.

The LLM groups accepted questions and answers into meaningful learning categories, with one repair attempt if grouping is invalid. Every category has at least five cards and each card is assigned once. Completed batches and categorized results are saved locally in .flashlearn/generation/ until card persistence finishes. Repeat the same command/provider/model/scope to resume failed work without repeating successful inference. Changed source content invalidates stale work; generate --fresh starts over. No API keys are checkpointed. Unfinished cards remain recoverable but are not added to the study deck. Offline and pre-existing untagged decks retain directory-based topics.

Offline mode is labeled section/doc-comment recall. --max-files caps eligible ranked files after scanning, not traversal. Longer runs are allowed; coverage and timing depend on source and model availability.

Inference default

When Copilot is detected, it appears first and is the interactive default: press Enter to use it. The menu states that this sends code and documentation to Copilot. Without Copilot, Enter selects heuristic. Noninteractive input remains offline unless inference is explicitly configured; type heuristic to select offline mode explicitly.