ColabEdu CLI Reference
ColabEdu CLI Reference
The ce-svc-cli is the command-line interface for operating the ColabEdu pedagogical curation pipeline. Commands are organized into nine functional groups:
| Group | Prefix | Description |
|---|---|---|
| Curator | curator | AI curation, Bloom derivation, E2E tests, and batch generation |
| Document Discovery | docs | Document discovery, download, and cataloging |
| Taxonomy | taxonomy | Standards, rubrics, and course exploration |
| Spec Batch | spec batch | Declarative, staged pipeline |
| Curriculum | curriculum | Gap analysis, ACA plan creation, progress tracking, and course provisioning |
| LMS | lms | E2E LMS provisioning, teardown, and bridge registration |
| User Operations | user | User provisioning |
| Grading | grading | Headless correction pipeline (Grading V2) |
| CRM Operations | crm | Lead import from CSV |
Environment Configuration
# Requiredexport CURATOR_API_BASE_URL=http://localhost:8081 # Backend URL (ce-svc-ai-services)export CE_SPECS_ROOT=/path/to/ce-specs # Specs repository root
# Optional (external source discovery)export COLABEDU_API_KEY_CANVAS=<token> # Canvas Commons APIexport COLABEDU_API_KEY_EUROPEANA=<wskey> # Europeana Education APIexport GOOGLE_CSE_API_KEY=<key> # Google Custom Search APIexport GOOGLE_CSE_ID=<cx> # Google CSE ID
# Optional (internal operations)export COLABEDU_API_BASE_URL=http://localhost:8081export COLABEDU_API_INTERNAL_KEY=<key> # X-Internal-API-KeyPipeline Overview Diagram
┌──────────────────────────────────────────────────────────────────────┐│ ColabEdu CLI — Pipeline Overview ││ ││ CLASSIC PIPELINE (Exam PDFs) ││ ──────────────────────────── ││ taxonomy check → docs discover → docs download → docs catalog ││ → curator curate → curator validate → sync_specs.sh ││ ││ LMS PIPELINE (Canvas/Moodle) ││ ──────────────────────────── ││ docs discover --source canvas-commons ││ → docs download → docs catalog --manifest lms_manifest.yaml ││ → curator batch → curator test --lms --all ││ ││ OER PIPELINE (CK-12/Khan/Procomún/Europeana) ││ ──────────────────────────────────────────── ││ docs discover --source ck12|europeana ││ → docs download → docs catalog ││ → curator curate --source-type OER_RESOURCE ││ --output-type RESOURCE_LEARNING ││ ││ DECLARATIVE BATCH PIPELINE ││ ────────────────────────── ││ spec batch generate → spec batch run → spec batch status ││ SEED & BLOOM PIPELINE (Content Derivation) ││ ────────────────────────────────────────── ││ curator curate --source book.pdf --visibility private ││ → curator bloom derive --seed <ref> --strategy PROGRESSION ││ ││ CURRICULUM PIPELINE (Gap-Driven ACA) ││ ──────────────────────────────────── ││ curriculum gaps --standard AP_SPANISH --country US ││ → curriculum plan create --theme <gap> --sources "url1,url2" ││ → curriculum progress (tracks all ACA plans per standard) ││ │└──────────────────────────────────────────────────────────────────────┘Group curator — AI Curation Pipeline
curator curate
Launches the AI curation pipeline on a local file or GCS URI and downloads the generated YAMLs.
curator curate --source <file-or-gs-uri> --referenceCode <code> [--sections "A,B"] [--type C2_EXERCISES] [--output <dir>] [--country <cc>] [--standard <std>] [--level <level>] [--subject <slug>] [--source-type WEB|LMS_PACKAGE] [--output-type RECIPE|INTERACTIVE_LESSON|RESOURCE_LEARNING] [--sandbox true|false] [--validate true|false] [--user <email>]Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--source | String | required | Local path (PDF, DOCX, .imscc, .mbz) or GCS URI (gs://...) |
--referenceCode | String | — | Taxonomic reference code (e.g. es.lomloe.bach.2.lcl). Auto-resolves standard, level, and subject. |
--sections | String | — | Comma-separated section names: "Section I,Section II" |
--type | String | C2_EXERCISES | Spec type to generate |
--output | String | ./curator_out | Output directory for YAMLs |
--country | String | (from referenceCode) | Country code override |
--standard | String | — | Curriculum standard override (e.g. LOMLOE, IB). Ignored when --referenceCode is used. |
--level | String | — | Education level override (e.g. 4 ESO, 2 BACH). Ignored when --referenceCode is used. |
--subject | String | — | Subject override (e.g. lcl, matematicas). Ignored when --referenceCode is used. |
--source-type | String | (auto) | WEB or LMS_PACKAGE. Auto-detected: .imscc/.mbz/.zip → LMS_PACKAGE. |
--output-type | String | RECIPE | RECIPE | INTERACTIVE_LESSON | RESOURCE_LEARNING |
--sandbox | boolean | true | Write YAMLs to disk without registering in DB |
--validate | boolean | true | Structurally validate downloaded YAMLs |
--user | String | — | Email of the user who will own the job. Without this flag, the job is created as shared (shared=true) and visible to all pedagogues with CONTENT_CREATOR, TEACHER, or ADMIN role. |
--visibility | String | PUBLIC | Visibility of the ingested spec: PUBLIC (available to all users) or PRIVATE (seed only — not served to students, used as derivation source for Bloom). |
Internal flow:
curator curate │ ├─ 1. POST /api/v1/curator/curate → workflowId │ (body: headless=true, sandboxMode, specType, referenceCode, │ rawContentBase64 / storageUrl, lmsSourceType, outputType) │ ├─ 2. Poll GET /api/v1/curator/status/{workflowId} │ every 3s, timeout: 300s │ states: RUNNING → COMPLETED | FAILED | ERROR │ ├─ 3. Download proposedSpecs[] → {workflowId}_spec_{n}_{outputType}_{ts}.yaml │ └─ 4. (optional) curator validate on each downloaded fileExamples:
# With referenceCode (recommended)curator curate \ --source ce-specs/sources/es/lomloe/2bach/lcl/exam_lcl_2023.pdf \ --referenceCode es.lomloe.bach.2.lcl
# With explicit flagscurator curate \ --source exam.pdf \ --standard LOMLOE --level "2 BACH" --subject lcl \ --sections "Option A,Option B" \ --type C2_EXERCISES# Canvas (.imscc) — source-type auto-detectedcurator curate \ --source ce-specs/sources/lms/canvas/canvas_bio_mitosis.imscc \ --referenceCode es.lomloe.bach.1.biologia \ --output-type INTERACTIVE_LESSON \ --sandbox
# Moodle (.mbz)curator curate \ --source math_course.mbz \ --referenceCode us.ap.calculus.bc \ --output-type INTERACTIVE_LESSON# From GCScurator curate \ --source gs://colabedu-sources/oer/ck12/ck12_bio_mitosis.json \ --referenceCode us.ap.biology \ --source-type OER_RESOURCE \ --output-type RESOURCE_LEARNING
# Local JSON OERcurator curate \ --source ck12_bio_mitosis.json \ --source-type OER_RESOURCE \ --output-type RESOURCE_LEARNING \ --sandbox# Without --user: job enters the shared queue# Visible to all CONTENT_CREATOR/TEACHER/ADMINcurator curate \ --source ce-specs/sources/us/ap/spanish/ap_spanish_2023.pdf \ --referenceCode us.ap.spanish_language.hl# → 🟡 "Shared" badge in the Job Command Center
# With --user: job assigned to a specific pedagoguecurator curate \ --source ap_spanish_2024.pdf \ --referenceCode us.ap.spanish_language.hl \ --user teacher@colabedu.org# → visible only for teacher@colabedu.orgcurator status
Checks the status of an ongoing or completed curation workflow.
curator status --id <workflowId>| Flag | Description |
|---|---|
--id | Required. Workflow ID returned by curator curate. |
Endpoint: GET /api/v1/curator/status/{workflowId}
Example:
curator status --id wf-20240601-abc123# → Workflow ID : wf-20240601-abc123# → Status : COMPLETED# → Specs ready : 2curator validate
Structurally validates a curator-generated YAML spec.
curator validate --spec <path-to-yaml>| Flag | Description |
|---|---|
--spec | Required. Path to the YAML file to validate. |
Checks that the YAML has metadata block (with type and id) and spec block (with exercises[].prompt if applicable).
Example:
curator validate --spec curator_out/wf-abc123_spec_1_recipe_20240601.yaml# → ✅ wf-abc123_spec_1_recipe_20240601.yaml — Valid YAML spec. All required fields present.curator test
Runs E2E test cases from the test manifest and generates a Markdown report.
curator test [--case <id>] [--all] [--manifest <path>] [--report true|false] [--output <dir>] [--lms]| Flag | Default | Description |
|---|---|---|
--case | — | Run a single test case by ID |
--all | false | Run all test cases in the manifest |
--manifest | ce-specs/tests/curator_test_manifest.yaml | Path to YAML manifest |
--report | true | Generate Markdown report in output directory |
--output | ./curator_out | Output directory (creates yyyy-MM-dd/ subdirectory) |
--lms | false | Use lms_curator_test_manifest.yaml instead of default |
Examples:
# Single case from classic manifestcurator test --case ap_spanish_2023_ordinaria
# All LMS/OER casescurator test --lms --all
# Custom manifestcurator test --manifest my-tests/batch_test.yaml --all --output ./results
# Without Markdown reportcurator test --all --report falsecurator batch
Generates specs for all documents in a manifest in production mode (no semantic comparison).
curator batch [--manifest <path>] [--output <dir>] [--country <cc>] [--standard <std>]| Flag | Default | Description |
|---|---|---|
--manifest | ce-specs/tests/curator_test_manifest.yaml | Path to YAML manifest |
--output | ./curator_out | Output directory |
--country | ES | Country code for curriculum context |
--standard | LOMLOE | Curriculum standard |
Example:
curator batch --manifest ce-specs/tests/lms_curator_test_manifest.yaml --output batch_output/curator bloom derive
Derives new pedagogical exercises from an ingested seed spec using a configurable Bloom strategy.
curator bloom derive --seed <referenceCode> [--strategy SOURCE_DERIVATION|PROGRESSION|MISCONCEPTION_REMEDIATION] [--context <standard/level/subject>] [--levels SIMPLIFIED,STANDARD,EXTENDED,CHALLENGE] [--count <n>] [--focus <topic>] [--output <dir>] [--sandbox]Flags:
| Flag | Default | Description |
|---|---|---|
--seed | required | referenceCode of the ingested seed spec |
--strategy | SOURCE_DERIVATION | Bloom strategy to apply |
--context | (from seed) | Curricular context: IB/HL/spanish_language |
--levels | (all 4) | Difficulty tiers (PROGRESSION only): SIMPLIFIED,STANDARD,EXTENDED,CHALLENGE |
--count | 2 | Number of exercises to generate (ignored for PROGRESSION) |
--focus | — | Topic or section to focus on within the seed |
--output | ./bloom_out | Output directory for generated YAML specs |
--sandbox | false | Generate YAML files locally without registering in SpecManager |
Endpoint: POST /api/v1/bloom/derive
Bloom Strategies:
| Strategy | Description | Best for |
|---|---|---|
SOURCE_DERIVATION | Default. Uses seed as L1 inspiration; generates L2–L6 as independent exercises. Copyright-safe. | Mass-scale derivation from exam PDFs |
PROGRESSION | Each difficulty tier builds on the previous. Generates SIMPLIFIED → STANDARD → EXTENDED → CHALLENGE. | Adaptive learning paths |
MEMORY_BLOOM | Only L1–L2 (recall + comprehension). Fast and lightweight. | Short seeds, vocabulary exercises |
APPLICATION_BLOOM | L3–L4 (application + analysis). Practice-focused. | Mid-level skills |
ANALYSIS_BLOOM | L4–L6 (analysis + synthesis + evaluation). Critical thinking. | Advanced / IB-style exercises |
Examples:
# Derive 3 exercises from a private source documentcurator bloom derive \ --seed ib.spa.textual_analysis_rubric \ --strategy SOURCE_DERIVATION \ --context IB/HL/spanish_language \ --count 3# → Generated: bloom_out/ib.spa.derived.ex_001.yaml# bloom_out/ib.spa.derived.ex_002.yaml# bloom_out/ib.spa.derived.ex_003.yaml# → Each YAML has metadata.provenance.seedRef = ib.spa.textual_analysis_rubric# Generate all 4 difficulty variants from an existing exercisecurator bloom derive \ --seed ib.spa.textual_analysis_ex_001 \ --strategy PROGRESSION# → Generated: *_SIMPLIFIED.yaml, *_STANDARD.yaml, *_EXTENDED.yaml, *_CHALLENGE.yaml
# Only generate two tierscurator bloom derive \ --seed ib.spa.textual_analysis_ex_001 \ --strategy PROGRESSION \ --levels SIMPLIFIED,CHALLENGE# Quick L1-L2 derivation for vocabulary seedscurator bloom derive \ --seed global.ib.spanish_b.vocab.unit3 \ --strategy MEMORY_BLOOM \ --count 5# → 5 recall/comprehension exercises, fast generation# Generate without registering (review before ingesting)curator bloom derive \ --seed ib.spa.lomloe_rubric_2025 \ --strategy SOURCE_DERIVATION \ --context LOMLOE/2BACH/lengua_castellana \ --count 2 \ --sandbox# → Written to ./bloom_out/ — NOT registered in SpecManager# → Run 'curator validate' + 'sync_specs.sh' when readyGroup docs — Document Discovery
docs discover
Discovers exam documents from known sources or web search.
docs discover [--query "<text>"] [--source <id>] [--subject <slug>] [--years "2022-2024"|"2022,2023"] [--call-type ordinaria|frq|mcq] [--output <file.yaml>] [--dry-run]| Flag | Description |
|---|---|
--query | Free-text for web search (requires Google CSE configured) |
--source | Known source ID: collegeboard, madrid, boe, canvas-commons, ck12, europeana… |
--subject | Subject slug: lcl, matematicas, spanish_language, biology… |
--years | Range "2022-2024" or list "2022,2023" |
--call-type | ordinaria | extraordinaria | frq | mcq |
--output | Saves discovery list to a YAML file |
--dry-run | List candidates without HTTP verification |
Internal strategies:
docs discover │ ├─ [--source canvas-commons|ck12|europeana] → LmsPackageDiscoveryStrategy (API) │ ├─ [--source collegeboard|madrid|boe...] → KnownSourcesStrategy (HEAD check URLs) │ └─ [--query "..."] → WebSearchStrategy (Google CSE)Examples:
# AP College Board examsdocs discover --source collegeboard --subject spanish_language --years 2020-2024 \ --output ap_spanish.yaml
# Spanish selectividad (Madrid)docs discover --source madrid --subject lcl --years 2022-2024 \ --call-type ordinaria --output selectividad_lcl.yaml
# Free web search (requires Google CSE)docs discover --query "AP Spanish Language and Culture 2023 exam" --output web_ap.yaml
# Canvas Commons packages (requires COLABEDU_API_KEY_CANVAS)docs discover --source canvas-commons --subject biology --output canvas_bio.yaml
# Europeana resources (requires COLABEDU_API_KEY_EUROPEANA)docs discover --source europeana --subject history --output europeana_history.yaml
# Dry-run to explore without downloadingdocs discover --source boe --subject matematicas --years 2023 --dry-rundocs download
Downloads documents from a discovery list to local disk.
docs download --list <discovery_list.yaml> [--local-dir <dir>] [--status FOUND] [--catalog true|false]| Flag | Default | Description |
|---|---|---|
--list | required | Path to YAML produced by docs discover |
--local-dir | — | Local directory to save downloads |
--status | FOUND | Only download documents with this status |
--catalog | true | Add downloaded docs to persistent source_catalog.yaml |
Example:
docs download --list ap_spanish.yaml --local-dir ce-specs/sources/us/ap/spanish/# → Updates source_catalog.yaml automatically# → Next step: docs catalog --list ap_spanish.yaml --manifest curator_manifest.yamldocs catalog
Adds documents from a discovery list to the curator manifest.
docs catalog --list <discovery_list.yaml> [--manifest <curator_manifest.yaml>] [--filter-status DOWNLOADED] [--dry-run]| Flag | Default | Description |
|---|---|---|
--list | required | Discovery list YAML |
--manifest | — | Curator manifest to append entries to |
--filter-status | DOWNLOADED | Only include documents with this status |
--dry-run | false | Print YAML to console without writing to disk |
Example:
docs catalog \ --list ap_spanish.yaml \ --manifest ce-specs/tests/curator_test_manifest.yaml
# Dry-run to review before writingdocs catalog --list ap_spanish.yaml --dry-rundocs search
Queries the local downloaded source catalog.
docs search [--subject <slug>] [--year <year>] [--source <id>] [--curator-status PENDING|DONE|FAILED]Example:
docs search --subject biology --curator-status PENDING# Lists all biology PDFs pending curationdocs sources
Lists all registered known document sources.
docs sources [--scope global|es|us] [--subject <slug>]Example:
docs sourcesdocs sources --scope us --subject spanish_languagedocs stats
Shows statistics from the local source catalog.
docs stats# → Total docs, by status, by subject, by sourceGroup taxonomy — Taxonomy Exploration
taxonomy standards
Lists all available curriculum standards, optionally filtered by country.
taxonomy standards [--country <cc>]# cc: es | us | mx | (empty = all)Endpoint: GET /api/v1/taxonomy/options/countries + /countries/{code}/standards
Example:
taxonomy standards --country us# 🇺🇸 United States# ├── std.intl.ap Advanced Placement (AP)# ├── std.us.tx.teks Texas Essential Knowledge and Skills# ├── std.intl.ib International Baccalaureate (IB)taxonomy tree
Shows the levels and subjects tree for a standard.
taxonomy tree --standard <std_id> [--subject <kw>]Endpoints:
GET /api/v1/taxonomy/options/standards/{std}/levelsGET /api/v1/taxonomy/options/standards/{std}/subjectsGET /api/v1/taxonomy/options/standards/{std}/subjects/{sval}/variants
Example:
taxonomy tree --standard std.intl.aptaxonomy tree --standard std.es.lomloe --subject lcltaxonomy rubrics
Lists available C0 rubrics in ce-specs/catalog/, with filter by standard and subject.
taxonomy rubrics [--standard <kw>] [--subject <kw>]Example:
taxonomy rubrics --standard ap --subject spanishtaxonomy rubrics --standard lomloe --subject matematicastaxonomy courses
Lists CourseBundle specs (BUNDLE_COURSE) for a country, standard, or referenceCode prefix.
taxonomy courses [--country <cc>] [--standard <kw>] [--referenceCode <prefix>]Endpoint: GET /api/v1/taxonomy/options/course-bundles?referenceCode=<prefix>
Example:
taxonomy courses --country es --standard lomloetaxonomy courses --referenceCode us.ap.spanish_languagetaxonomy check
Full pre-flight check for a referenceCode before curation. Verifies:
- ✅ Taxonomy in DB (
/api/v1/taxonomy/options/resolve) - 📐 C0 rubrics in
ce-specs/catalog/ - 🧪 C1 recipes in
ce-specs/catalog/ - 📄 PDFs in
ce-specs/sources/ - 📦 CourseBundles in DB
- 📄 Already-curated specs in
curator_out/
taxonomy check --referenceCode <code>Example:
taxonomy check --referenceCode us.ap.spanish_language.hl# ╔══════════════════════════════════════════════════════════╗# ║ Pre-flight Check: us.ap.spanish_language.hl ║# ╚══════════════════════════════════════════════════════════╝# 📚 TAXONOMY (DB)# Standard: AP# Level: HL# ...# RESULT: ✅ Ready to curatetaxonomy report
Generates a status table for all standards of a country (or all countries).
taxonomy report [--country <cc>] [--save]| --save | false | Save report as Markdown to curator_out/taxonomy_report.md |
Example:
taxonomy report --country es --savetaxonomy report # All countriestaxonomy catalog list
Lists all specifications registered in the ColabEdu catalog, with filters for ID prefix, specification type, and status. It attempts to query the backend remotely; if not available, it performs a local scan of YAML files.
taxonomy catalog list [--root <prefix>] [--type <type>] [--status <status>] [--format table|json] [--local] [--remote]Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--root | String | — | ID prefix to filter (e.g. es.c0, std.intl, bundle.us) |
--type | String | — | Specification type (e.g. BLOCK_RUBRIC, TAXONOMY, BUNDLE_COURSE, RECIPE, PERSONA, STANDARD_SPEC, COURSE_SPEC, PATHWAY_BUNDLE) |
--status | String | — | Spec status (PUBLISHED, DRAFT, ARCHIVED) |
--format | String | table | Output format: table or json |
--local | boolean | false | Force local YAML scan in ce-specs without querying the backend |
--remote | boolean | false | Force remote backend API query |
Example:
taxonomy catalog list --root es.lomloe --type RECIPEtaxonomy catalog list --type STANDARD_SPEC --localtaxonomy catalog show
Shows full details of a specification by its reference code (referenceCode or id), including all public canonical IDs and the corresponding YAML.
taxonomy catalog show --id <referenceCode> [--format detail|yaml]| Flag | Type | Default | Description |
|---|---|---|---|
--id | String | required | Spec ID or referenceCode to inspect |
--format | String | detail | Display format: detail (structured info) or yaml (full YAML code) |
Example:
taxonomy catalog show --id global.c1.ib.spanish_b.sl.debate.v1 --format yamltaxonomy catalog tree
Shows a hierarchical tree representation of catalog specifications organized under a common prefix.
taxonomy catalog tree [--root <prefix>] [--depth <N>]| Flag | Type | Default | Description |
|---|---|---|---|
--root | String | — | Root ID prefix to build the tree (e.g. es.lomloe) |
--depth | int | 3 | Maximum depth of the hierarchy tree |
Example:
taxonomy catalog tree --root es.lomloe.bach.2taxonomy catalog export
Exports filtered catalog specifications to a local file in JSON or YAML format.
taxonomy catalog export [--root <prefix>] [--type <type>] [--out <file>] [--format json|yaml]| Flag | Type | Default | Description |
|---|---|---|---|
--root | String | — | ID prefix to filter exports |
--type | String | — | Specification type to export |
--out | String | — | Destination file path (if omitted, prints to console) |
--format | String | yaml | Export format: json or yaml |
Example:
taxonomy catalog export --root es.lomloe --type BLOCK_RUBRIC --out rubricas_lomloe.yamltaxonomy catalog docs
Dynamically generates the MDX catalog reference documentation page (catalog.mdx) in both English and Spanish under the ce-web paths.
taxonomy catalog docsThis command scans all available specifications, groups them by educational layers (C0 to C3), and outputs structured summary tables with their respective canonical IDs.
Example:
taxonomy catalog docsGroup spec batch — Declarative Pipeline
spec batch run
Executes a staged spec pipeline from a YAML definition file.
spec batch run --batch <file.yaml> [--from <stage>] [--dry-run]| Flag | Description |
|---|---|
--batch | Required. Path to the batch YAML definition file |
--from | Resume from stage: taxonomy | discover | fetch | parse | approval | ingest |
--dry-run | Show execution plan without running anything |
Pipeline stages:
taxonomy → discover → fetch → parse → approval → ingestState is persisted in .ce-batch-state.json to allow resuming on failure.
Example:
spec batch run --batch batch_ap_spanish.yamlspec batch run --batch batch_ap_spanish.yaml --dry-runspec batch run --batch batch_ap_spanish.yaml --from parse # Resume from parsespec batch status
Shows the status of the last batch run (or by ID).
spec batch status [--batch-id <id>]Reads .ce-batch-state.json from the current directory.
Example:
spec batch status# Batch ID : batch-ap-spanish-2024# Status : ✅ COMPLETED# Discovered URLs : 12# Fetched files : 11# Parsed specs : 10# Ingested ref codes : 10spec batch generate
Generates a batch YAML definition from a natural language description using AI.
spec batch generate --description "<description>" [--out batch.yaml] [--print]| Flag | Default | Description |
|---|---|---|
--description | required | High-level description of pedagogical content to ingest |
--out | batch.yaml | Output file |
--print | — | Print YAML to console instead of saving |
Endpoint: POST /api/v1/curator/batch/generate
Example:
spec batch generate \ --description "AP Spanish courses for high school in California" \ --out batch_ap_ca.yaml
spec batch generate --description "LOMLOE math exams 4 ESO" --printGroup curriculum — Curriculum Gap & Planning
The curriculum command group integrates the CurriculumArchitectService with the CLI. It reads curriculum requirements from spec-as-code YAML files (ce-specs/catalog/requirements/) to identify what specs are missing, and can launch targeted ACA plans to fill those gaps automatically.
curriculum gaps
Returns a structured gap analysis comparing existing specs against curriculum requirements.
curriculum gaps --standard <STD> --country <CC>| Flag | Type | Required | Description |
|---|---|---|---|
--standard | String | ✅ | Curricular standard code (e.g. AP_SPANISH, LOMLOE) |
--country | String | ✅ | ISO country code (US, ES, MX…) |
Endpoint: GET /api/v1/curriculum/gaps?standard=&country=
Example:
curriculum gaps --standard AP_SPANISH --country US# 📊 Curriculum Gap Analysis — AP_SPANISH / US# Coverage : 42.0% (21 / 50 specs)## Theme SpecType REQ HAVE GAP# ──────────────────────────────────────────────────────────────# ❌ simulated_conversation C2_EXERCISES 10 2 8# ❌ simulated_conversation INTERACTIVE_LESSON 5 0 5# ⚠️ email_reply C2_EXERCISES 8 4 4# ✅ cultural_comparison C2_EXERCISES 6 6 0Icons:
- ✅
coverage ≥ 100%— fully covered - ⚠️
coverage 50–99%— partially covered - ❌
coverage < 50%— critical gap
curriculum progress
Shows the aggregated ACA pipeline state across all plans for a given standard + country.
curriculum progress --standard <STD> --country <CC>| Flag | Type | Required | Description |
|---|---|---|---|
--standard | String | ✅ | Curricular standard code |
--country | String | ✅ | ISO country code |
Endpoint: GET /api/v1/curriculum/progress?standard=&country=
Example:
curriculum progress --standard AP_SPANISH --country US# 🚀 Curriculum Progress — AP_SPANISH / US# Overall : 58.0% complete# Items : 8 DONE | 1 PENDING | 1 REVIEW | 0 FAILED## Plan STATUS STAGE DONE PEND REV FAIL# ─────────────────────────────────────────────────────────────────────────────# CURRICULUM-AP_SPANISH-US-simulated... RUNNING c2_exercises 4 1 0 0# CURRICULUM-AP_SPANISH-US-email_reply COMPLETED c2_exercises 4 0 1 0curriculum plan create
Creates and immediately launches an ACA curator plan to fill a specific curriculum gap.
The plan name is auto-generated as CURRICULUM-{standard}-{country}-{theme}-{specType}.
curriculum plan create --standard <STD> --country <CC> --theme <themeId> --spec-type <TYPE> --sources "<url1>,<url2>,..." [--subject <subject>] [--level <level>]| Flag | Default | Description |
|---|---|---|
--standard | required | Curricular standard (e.g. AP_SPANISH) |
--country | required | ISO country code (US, ES…) |
--theme | required | Theme ID from the requirements YAML (e.g. simulated_conversation) |
--spec-type | C2_EXERCISES | Spec type to produce: C2_EXERCISES, INTERACTIVE_LESSON, BLOCK_RUBRIC… |
--sources | required | Comma-separated source URLs to curate |
--subject | spanish | Subject area override |
--level | 9-12 | Education level override |
Endpoint: POST /api/v1/curriculum/plans
Example:
curriculum plan create \ --standard AP_SPANISH \ --country US \ --theme simulated_conversation \ --spec-type C2_EXERCISES \ --sources "https://apcentral.collegeboard.org/media/pdf/ap23-apc-spanish-language.pdf,https://apcentral.collegeboard.org/media/pdf/ap22-apc-spanish-language.pdf"# ✅ ACA Plan created and launched# Plan ID : e4a1c230-...# Items queued : 2# Status : RUNNING## Monitor with:# aca plan status --id e4a1c230-...# curriculum progress --standard AP_SPANISH --country UScurriculum bundle assemble
Assembles a BUNDLE_COURSE spec by grouping seeds and their Bloom-derived exercises into a coherent pedagogical unit.
curriculum bundle assemble \ --standard <STD> \ --level <level> \ --strategy SEED_AND_BLOOM \ [--referenceCode <prefix>]| Flag | Default | Description |
|---|---|---|
--standard | required | Curricular standard |
--level | required | Education level (e.g. HL, SL, 2BACH) |
--strategy | SEED_AND_BLOOM | Assembly strategy |
--referenceCode | (auto) | Prefix to filter seeds (e.g. global.ib.spanish_b.paper2) |
Example:
curriculum bundle assemble \ --standard IB \ --level HL \ --strategy SEED_AND_BLOOM# → Bundle assembled: global.ib.spanish_b.paper2.hl.bundle.v1# → Contains: 15 seeds + 75 Bloom derivations (L2-L6)curriculum bundle status
Shows the ingestion and delivery status of a curriculum bundle.
curriculum bundle status --bundle-ref <referenceCode>Example:
curriculum bundle status --bundle-ref global.ib.spanish_b.paper2.hl.bundle.v1# Status: READY# Seeds: 15 | Bloom derivations: 75 | Pathways: 2 (HL + SL)curriculum catalog list
Lists all available curriculum bundles ready for teacher assignment.
curriculum catalog list [--standard <STD>] [--country <CC>]Endpoint: GET /api/v1/curriculum/catalog
Example:
curriculum catalog list# ┌─────────────────────────────────────────────┬──────────────┬────────┐# │ Bundle Ref │ Standard │ Status │# ├─────────────────────────────────────────────┼──────────────┼────────┤# │ global.ib.spanish_b.paper2.hl.bundle.v1 │ IB Spanish B │ READY │# │ us.ap.spanish_language.frq.bundle.v1 │ AP Spanish │ READY │# │ es.ebau.lcl.madrid.bundle.v1 │ EBAU Madrid │ READY │# └─────────────────────────────────────────────┴──────────────┴────────┘curriculum teacher view
Displays assigned curriculum bundles and course progress for a specific teacher.
curriculum teacher view --teacher-id <userId>Endpoint: GET /api/v1/curriculum/my/overview?teacherIdParam=<userId>
Example:
curriculum teacher view --teacher-id 42# Teacher: teacher@colabedu.org (ID: 42)# ├── Course: IB Spanish B HL 2024 → 3 classrooms, 67% progress# └── Course: AP Spanish Language → 1 classroom, 45% progresscurriculum course provision
Provisions a curriculum bundle as a live course in the relational database (organizations → courses → classrooms).
curriculum course provision \ --bundle-ref <referenceCode> \ --org-id <orgId> \ --teacher-id <userId>| Flag | Description |
|---|---|
--bundle-ref | required. referenceCode of an assembled bundle |
--org-id | required. Organization ID |
--teacher-id | required. Teacher user ID who will own the course |
Endpoint: POST /api/v1/curriculum/course
Example:
curriculum course provision \ --bundle-ref global.ib.spanish_b.paper2.hl.bundle.v1 \ --org-id 5 \ --teacher-id 42# ✅ Course provisioned# Course ID : 88# Name : IB Spanish B — Paper 2 HL# Teacher : teacher@colabedu.org# Classrooms : 0 (ready for enrollment)Integrated Workflow: Seed & Bloom + Curriculum Lifecycle
This is the full end-to-end workflow for onboarding a new curriculum standard from scratch:
-
Analyze gaps — Understand what’s missing before starting any batch.
Ventana de terminal curriculum gaps --standard IB --country global# → Identify: Paper 2 Writing (HL+SL) has 12-spec deficit -
Discover & fetch sources — Find official exam documents.
Ventana de terminal docs discover --source ibdocs --subject spanish_b --years 2019-2024 \--output ib_sb_sources.yamldocs download --list ib_sb_sources.yaml --local-dir ce-specs/sources/ib/spanish_b/ -
Ingest seeds — Curate PDFs into private BLOCK_CONTENT specs (F3).
Ventana de terminal # Using batch YAML for production runsspec batch run ce-specs/batches/batch_25_ib_spanish_b_seeds_paper2.yaml# Or individually:curator curate \--source ce-specs/sources/ib/spanish_b/ib_paper2_hl_nov2023.pdf \--referenceCode global.ib.spanish_b.paper2.hl.nov2023 \--visibility PRIVATE -
Expand with Bloom — Derive L2–L6 exercises from each seed (F4).
Ventana de terminal spec batch run ce-specs/batches/batch_26_ib_spanish_b_bloom_expand.yaml# Or for a single seed:curator bloom derive \--seed global.ib.spanish_b.paper2.hl.nov2023 \--strategy SOURCE_DERIVATION \--count 5 -
Assemble bundles — Group seeds + derivations into course units (F5).
Ventana de terminal spec batch run ce-specs/batches/batch_27_ib_spanish_b_assemble_bundles.yaml# Or:curriculum bundle assemble --standard IB --level HL --strategy SEED_AND_BLOOM -
Publish pathways — Materialize as Teacher Dashboard entries (F6).
Ventana de terminal spec batch run ce-specs/batches/batch_28_ib_spanish_b_assemble_pathways.yaml -
Verify coverage — Check the sprint improved the curriculum.
Ventana de terminal curriculum progress --standard IB --country global# Paper 2 Writing: 93% (14/15 specs) ✅ -
Provision course — Create live course for a teacher (F7).
Ventana de terminal curriculum catalog list # find the bundle refcurriculum course provision \--bundle-ref global.ib.spanish_b.paper2.hl.bundle.v1 \--org-id 5 --teacher-id 42 -
Connect to LMS — Register LTI bridge for Canvas/Moodle delivery.
Ventana de terminal lms provision --file lms-ib-spanish-b.yaml --suffix ib-sprint-01lms register-link \--classroom-id <colabedu_classroom_id> \--spec-ref global.ib.spanish_b.paper2.hl.bundle.v1 \--lms-platform canvas \--lms-assignment-id <canvas_assignment_id>
Group lms — LMS E2E Operations
Commands for provisioning, tearing down, and inspecting LMS test fixtures (Canvas / Moodle), and for registering the LTI bridge without manual Deep Linking.
All lms commands require the following env vars or application.properties entries:
lms.canvas.url=https://your-canvas.instructure.comlms.canvas.admin-token=<admin_token>lms.moodle.url=https://your-moodle.example.comlms.moodle.admin-token=<wstoken>lms provision
Provisions a complete LMS environment (organizations → courses → users → assignments) from a YAML template on every configured platform.
All created resources are named with <suffix> to enable safe selective teardown.
lms provision --file <yaml> --suffix <suffix> [--dry-run] [--canvas-only] [--moodle-only]| Flag | Default | Description |
|---|---|---|
--file | required | Path to YAML fixture template (supports {{suffix}} tokens) |
--suffix | required | Run-specific suffix appended to all resource names (e.g. lms-test-20260622) |
--dry-run | false | Validates YAML and prints plan without executing any remote calls |
--canvas-only | false | Skip Moodle, only provision Canvas |
--moodle-only | false | Skip Canvas, only provision Moodle |
Endpoint: POST /ops/v1/lms/provision-lms-from-yaml
Timeout: 180 s (Canvas/Moodle calls are remote — generous read timeout applied automatically)
Example YAML template (lms-ib-spanish-b.yaml):
organizations: - name: "Test School {{suffix}}" courses: - name: "IB Spanish B HL {{suffix}}" courseCode: "IB-SPA-B-HL-{{suffix}}" users: - email: teacher@test.com role: teacher - email: student1@test.com role: student assignments: - name: "Paper 2 Writing HL {{suffix}}" points: 20Example:
lms provision \ --file ce-specs/e2e/lms-ib-spanish-b.yaml \ --suffix ib-sprint-01
# 🏗️ LMS Provision — suffix=ib-sprint-01# ══════════════════════════════════════════════# Courses created: 2# ✅ [canvas] id=678 IB Spanish B HL ib-sprint-01# ✅ [moodle] id=42 IB Spanish B HL ib-sprint-01# Users enrolled: 4# Assignments created: 4# 📝 [canvas] id=456 Paper 2 Writing HL ib-sprint-01## ✅ Done — suffix=ib-sprint-01# ℹ️ Next: run 'lms register-link' to activate the B→C bridge.
# Dry run (no remote calls):lms provision --file lms-ib-spanish-b.yaml --suffix ib-sprint-01 --dry-run# → [DRY RUN] YAML read OK — 22 lines. {{suffix}} tokens: 6. No LMS resources created.lms teardown
Selectively deletes LMS courses whose names contain the supplied suffix.
Safety contract: LTI developer keys, tool registrations, admin accounts, and any course not matching the suffix are never touched.
lms teardown --suffix <suffix> [--dry-run] [--canvas-only] [--moodle-only]| Flag | Default | Description |
|---|---|---|
--suffix | required | Only courses containing this string (case-insensitive) are deleted |
--dry-run | false | Lists what would be deleted without executing |
--canvas-only | false | Only teardown Canvas |
--moodle-only | false | Only teardown Moodle |
Endpoint: POST /ops/v1/lms/teardown-test-data
Example:
# Preview firstlms teardown --suffix ib-sprint-01 --dry-run# 🗑️ LMS Teardown — suffix=ib-sprint-01 [DRY RUN]# ⚠️ Only courses matching suffix 'ib-sprint-01' will be deleted.# 🔍 IB Spanish B HL ib-sprint-01# 🔍 IB Spanish B SL ib-sprint-01
# Execute teardownlms teardown --suffix ib-sprint-01# 🗑️ LMS Teardown — suffix=ib-sprint-01# Deleted: 2 Skipped: 47# 🗑️ IB Spanish B HL ib-sprint-01# 🗑️ IB Spanish B SL ib-sprint-01# ✅ Teardown complete. LTI keys and admin config untouched.lms register-link
Seeds lms_resource_links.lms_assignment_id in the ColabEdu database to activate the B→C bridge without performing a manual LTI Deep Link launch in Canvas or Moodle.
Required before running the student submission test flow (Phase 5 of the E2E orchestrator).
lms register-link \ --classroom-id <id> \ --spec-ref <referenceCode> \ --lms-platform <canvas|moodle> \ --lms-assignment-id <id> \ [--lms-course-id <id>]| Flag | Description |
|---|---|
--classroom-id | required. ColabEdu classroom ID |
--spec-ref | required. OAS referenceCode of the spec to bind (e.g. global.ib.spanish_b.paper2.hl.bundle.v1) |
--lms-platform | required. canvas or moodle |
--lms-assignment-id | required. Native LMS assignment ID (e.g. Canvas 456) |
--lms-course-id | (optional) LMS course ID for multi-course validation |
Endpoint: POST /ops/v1/lms/register-link
Example:
lms register-link \ --classroom-id 13 \ --spec-ref global.ib.spanish_b.paper2.hl.bundle.v1 \ --lms-platform canvas \ --lms-assignment-id 456
# ✅ register-link OK# classroomId = 13# specRef = global.ib.spanish_b.paper2.hl.bundle.v1# lmsPlatform = canvas# lmsAssignmentId = 456# resourceLinkId = 3f9a1b22-...# bridgeStatus = ACTIVElms status
Displays a unified read-only view of LMS resources and active bridge links matching a given suffix. Combines three backend queries: course list, provision status, and registered resource links.
lms status --suffix <suffix> [--canvas-only] [--moodle-only]| Flag | Default | Description |
|---|---|---|
--suffix | required | Suffix filter to match resources |
--canvas-only | false | Only query Canvas |
--moodle-only | false | Only query Moodle |
Endpoints called:
GET /ops/v1/lms/courses?platform=&nameFilter=<suffix>— list matching courses per platformGET /ops/v1/lms/status?suffix=<suffix>— provision status summaryGET /ops/v1/lms/resource-links?suffixFilter=<suffix>— active bridge links
Example:
lms status --suffix ib-sprint-01
# ══════════════════════════════════════════════════════════════════════# LMS Status — suffix=ib-sprint-01# ══════════════════════════════════════════════════════════════════════## [canvas] Courses:# 678 IB Spanish B HL ib-sprint-01 [courseCode=IB-SPA-B-HL-ib-sprint-01]# 679 IB Spanish B SL ib-sprint-01 [courseCode=IB-SPA-B-SL-ib-sprint-01]## [moodle] Courses:# 42 IB Spanish B HL ib-sprint-01## Bridge Links:# canvas assignmentId=456 specRef=global.ib.spanish_b.paper2.hl.bundle.v1 status=ACTIVE# moodle assignmentId=cmid:37 specRef=global.ib.spanish_b.paper2.sl.bundle.v1 status=ACTIVEGroup user — User Operations
user provision
Provisions a single user via the backend Ops API.
user provision --email <email> --name "<name>" [--role "teacher;admin"]| Flag | Default | Description |
|---|---|---|
--email | required | User email |
--name | required | Full name |
--role | teacher | Semicolon-separated roles (e.g. teacher;admin) |
Endpoint: POST /ops/v1/provisioning/trigger
user bulk-provision
Bulk-provisions users from a CSV file (email,name,role).
user bulk-provision --file <users.csv>Example CSV:
email,name,rolejohn@school.edu,John Smith,teacheradmin@school.edu,Admin User,teacher;adminGroup crm — CRM Operations
crm import-leads
Bulk-imports leads into CRM from a CSV file (email,name,state,subject).
crm import-leads --file <leads.csv> [--owner <ownerId>]Endpoint: POST /ops/v1/provisioning/crm/leads/ingest
Complete Workflow Examples
Workflow A: AP Exam Curation (Classic)
# 1. Pre-flight checktaxonomy check --referenceCode us.ap.spanish_language.hl
# 2. Discover and download sourcesdocs discover --source collegeboard --subject spanish_language --years 2020-2024 \ --output ap_spanish.yamldocs download --list ap_spanish.yaml --local-dir ce-specs/sources/us/ap/spanish/
# 3. Add to manifest and curatedocs catalog --list ap_spanish.yaml \ --manifest ce-specs/tests/curator_test_manifest.yamlcurator test --case ap_spanish_2023_ordinaria
# 4. Curate a specific documentcurator curate \ --source ce-specs/sources/us/ap/spanish/ap_spanish_2023.pdf \ --referenceCode us.ap.spanish_language.hl \ --sections "Section I,Section II"
# 5. Validate and ingestcurator validate --spec curator_out/wf-abc123_spec_1_recipe_20240601.yamlbash sync_specs.sh local GLOBALWorkflow B: Canvas LMS Batch
# 1. Discover Canvas Commons packagesdocs discover --source canvas-commons --subject biology --output canvas_bio.yaml
# 2. Downloaddocs download --list canvas_bio.yaml --local-dir ce-specs/sources/lms/canvas/
# 3. Create LMS manifestdocs catalog --list canvas_bio.yaml \ --manifest ce-specs/tests/lms_curator_test_manifest.yaml
# 4. Run batchcurator batch --manifest ce-specs/tests/lms_curator_test_manifest.yaml \ --output batch_output/
# 5. Test LMScurator test --lms --allWorkflow C: Declarative Batch Pipeline
# 1. Generate definition from natural languagespec batch generate \ --description "selectividad Spanish language exams Madrid 2020-2024" \ --out batch_lcl_madrid.yaml
# 2. Review and executespec batch run --batch batch_lcl_madrid.yaml --dry-runspec batch run --batch batch_lcl_madrid.yaml
# 3. Check statusspec batch statusWorkflow D: Shared Pedagogical Review Queue
# 1. Launch curation from CI/CD or CLI (no user assigned)curator curate \ --source ce-specs/sources/us/ap/spanish/ap_spanish_2024.pdf \ --referenceCode us.ap.spanish_language.hl# → job created with shared=true# → 🟡 "Shared" badge appears in Job Command Center for all TEACHER/CONTENT_CREATOR
# 2. (Optional) Assign to a specific pedagoguecurator curate \ --source ap_spanish_2024.pdf \ --referenceCode us.ap.spanish_language.hl \ --user pedagogue@colabedu.org# → job.shared = false, job.owner_email = "pedagogue@colabedu.org"# → visible only for that user
# 3. Check job statuscurator status --id <workflowId>
# 4. Pedagogue approves the job from the Job Command Center in the web UI# → Status: PENDING_REVIEW → APPROVED → automatic registration in SpecManager
# 5. Ingest approved specsbash sync_specs.sh local GLOBALWorkflow E: Seed & Bloom — Content Derivation
# STEP 1: Ingest a private source document as a seedcurator curate \ --source ce-specs/sources/seeds/ib_spa_textual_analysis_guide.pdf \ --referenceCode ib.spa.textual_analysis_rubric \ --visibility private# → spec ingested with visibility=PRIVATE# → NOT served to students, only used as derivation source
# STEP 2: Derive exercises from the seedcurator bloom derive \ --seed ib.spa.textual_analysis_rubric \ --strategy SOURCE_DERIVATION \ --context IB/HL/spanish_language \ --count 4 \ --focus "Section 1: Reading Comprehension"# → 4 derived ExerciseSpec YAMLs in bloom_out/# → Each has: metadata.provenance.seedRef = ib.spa.textual_analysis_rubric# → visibility: PUBLIC
# STEP 3 (optional): Generate difficulty tiers from a derived exercisecurator bloom derive \ --seed ib.spa.derived.textual_analysis_ex_001 \ --strategy PROGRESSION# → SIMPLIFIED / STANDARD / EXTENDED / CHALLENGE variants
# STEP 4: Review and ingestcurator validate --spec bloom_out/ib.spa.derived.textual_analysis_ex_001.yamlbash sync_specs.sh local GLOBALWorkflow F: Curriculum Gap → ACA Sprint
# 1. Check what specs are missing for AP Spanishcurriculum gaps --standard AP_SPANISH --country US# → Coverage 42%, critical gaps in simulated_conversation and email_reply
# 2. Discover relevant source documentsdocs discover --source collegeboard --subject spanish_language --years 2020-2024 \ --output ap_spanish.yaml
# 3. Download sourcesdocs download --list ap_spanish.yaml --local-dir ce-specs/sources/us/ap/spanish/
# 4. Launch targeted ACA plan for the top gap (simulated_conversation)curriculum plan create \ --standard AP_SPANISH \ --country US \ --theme simulated_conversation \ --spec-type C2_EXERCISES \ --sources "$(grep 'url:' ap_spanish.yaml | awk '{print $2}' | tr '\n' ',' | sed 's/,$//') "# → Plan created: CURRICULUM-AP_SPANISH-US-simulated_conversation-C2_EXERCISES
# 5. Monitor ACA pipeline progresscurriculum progress --standard AP_SPANISH --country US# → Overall 58% complete, 8 DONE, 1 PENDING
# 6. Handle NEEDS_REVIEW itemsaca plan list <planId> --status NEEDS_REVIEWaca plan approve <planId> --item <itemId>
# 7. Verify gap closurecurriculum gaps --standard AP_SPANISH --country US# → simulated_conversation C2_EXERCISES: 10/10 ✅