@lxpack/cli

Command-line tool for scaffolding, previewing, validating, and packaging LXPack courses.

Part of LXPack. Docs: CLI reference · File-based authoring.

| Related | Package | |---------|---------| | Programmatic API | @lxpack/api | | Validation | @lxpack/validators | | Browser runtime | @lxpack/runtime | | Export / ZIP | @lxpack/scorm | | Lesson widgets | @lxpack/components |

Install

See Install the CLI.

npm install -g @lxpack/cli
# or: pnpm add -g @lxpack/cli

Requires Node.js 18 or 20 (18+).

Quick start

Tutorial: Your first course.

lxpack init my-course
cd my-course
lxpack preview          # http://127.0.0.1:3847 by default
lxpack validate
lxpack build --target scorm12
lxpack build --target scorm2004
lxpack build --target xapi
lxpack build --target cmi5

Output lands in .lxpack/ unless overridden by -o or lxpack.config.json.

Commands

Authoritative option list: CLI reference. Export targets: Export to LMS.

| Command | Description | |---------|-------------| | init <name> | Scaffold a new course (-d, --dir <path>, -f, --force) | | preview | Start local preview server (-p, --port, -H, --host) | | validate | Validate course.yaml and referenced files (-t, --target for export checks) | | build | Package for LMS or standalone export |

build options

| Option | Description | |--------|-------------| | -t, --target <target> | scorm12 (default), scorm2004, standalone, xapi, or cmi5 | | -o, --output <path> | Output ZIP file or directory | | --dir | Write an unpacked directory instead of a ZIP |

build and preview use the same validation rules: errors fail the command (exit code 1). build reuses the validated manifest and bakes a sanitized assessment bundle into the exported HTML config.

SCORM 2004 builds produce a multi-SCO ZIP: one launch page per activity under sco/<activityId>/index.html, plus shared lxpack-runtime.js and lxpack-components.js.

Preview serves the runtime client and optional components bundle at /runtime/components.js. Configure SCORM simulators in lxpack.config.json:

{ "preview": { "scormMode": "local" } }

| scormMode | Behavior | |-------------|----------| | local | localStorage progress (default) | | scorm12 | SCORM 1.2 simulator on window.API | | scorm2004 | SCORM 2004 simulator on window.API_1484_11 |

Direct HTTP access to assessments/, course.yaml, lxpack.config.json, and .lxpack/ under /course/ returns 404; quiz content is embedded in the preview page config only.

Course discovery

Commands walk up from the current working directory until they find course.yaml. Run them from inside your course project (or a subdirectory).

Path safety

• init --dir must be a relative path that stays inside the current working directory.
• lxpack.config.json output.dir is resolved relative to the course root with the same containment rules.

Course layout

Course structure · course.yaml · lxpack.config.json.

my-course/
  course.yaml
  lxpack.config.json   # optional: defaultTarget, output
  lessons/
  interactions/
  assessments/         # authoring only — omitted from export ZIPs
  components/          # optional widget overrides
  assets/
  .gitignore           # .lxpack/, *.zip (assessments/ stay tracked)
  .lxpack/             # build output (generated)

init scaffolds commented examples for variables, flow, and type: component lessons. See branching-demo for variables, flow, and components.

lxpack.config.json

{
  "defaultTarget": "scorm12",
  "output": {
    "dir": ".lxpack"
  }
}

Use "defaultTarget": "scorm2004" when your LMS expects SCORM 2004 4th Edition packages.

See course.yaml reference and branching for full examples.

Programmatic use

The CLI is built with Commander. validate and build delegate to @lxpack/api, which returns structured results instead of exiting the process.

import { validateCourse, buildCourse } from "@lxpack/api";

const result = await validateCourse({ courseDir: "/path/to/course", target: "scorm12" });
if (!result.ok) {
  for (const issue of result.issues) console.error(issue.path, issue.message);
}

await buildCourse({ courseDir: "/path/to/course", target: "scorm12" });

For lower-level control, depend on @lxpack/validators, @lxpack/scorm, @lxpack/runtime, and @lxpack/components directly. LessonKit workflows: LessonKit & React hub.

Development

From the monorepo root:

pnpm --filter @lxpack/cli build
pnpm --filter @lxpack/cli test
pnpm --filter @lxpack/cli typecheck

Links

• LXPack repository
• Documentation
• CLI reference
• Roadmap & phases
• Changelog

License

Apache-2.0