npm package: @scholium/cli
Description: CLI tools for Scholium Curriculum Package creation and validation
Author: Scholium
Latest version: 1.0.0

# @scholium/cli

Command-line tools for creating and validating Scholium Curriculum Packages (.spkg).

## Installation

```bash
# Run directly with npx (no install needed)
npx @scholium/cli validate my-curriculum.spkg

# Or install globally
npm install -g @scholium/cli
```

## Commands

### `validate` - Validate a curriculum package

Validates a `.spkg` or `.zip` curriculum package and reports any errors or warnings.

```bash
scholium validate <file> [options]
```

**Options:**
- `--json` - Output results as JSON (useful for CI/CD pipelines)
- `--strict` - Treat warnings as errors (exit code 1 if any warnings)
- `--quiet` - Only output errors, suppress success messages

**Examples:**
```bash
# Basic validation
scholium validate my-curriculum.spkg

# JSON output for scripting
scholium validate my-curriculum.spkg --json

# Strict mode for CI
scholium validate my-curriculum.spkg --strict
```

**Output:**
```
✓ Package: my-curriculum.spkg (2.4 MB)

Stats
─────
  Modules      5
  Topics       23
  Items        245
  Flashcards   156
  Quizzes      89
  Media Files  12

2 warnings
──────────
⚠ [MISSING_EXPLANATION] at modules[1].topics[2].items[5]: MCQ is missing an explanation
⚠ [FLASHCARD_REVERSED] at modules[3].topics[0].items[2]: Flashcard may be reversed (back is shorter than front)

✓ Package is valid
```

---

### `inspect` - Inspect package contents

View the contents and structure of a curriculum package without validating.

```bash
scholium inspect <file> [options]
```

**Options:**
- `--manifest` - Show only manifest information
- `--tree` - Show content tree structure
- `--items` - List all items with their IDs
- `--media` - List media files grouped by type

**Examples:**
```bash
# Full overview
scholium inspect my-curriculum.spkg

# Just the manifest
scholium inspect my-curriculum.spkg --manifest

# List all item IDs (useful for debugging)
scholium inspect my-curriculum.spkg --items
```

---

### `create` - Create a new package scaffold

Generate a new curriculum package with template files to get started quickly.

```bash
scholium create <name> [options]
```

**Options:**
- `-t, --template <type>` - Template type: `basic`, `medical`, or `language` (default: `basic`)
- `-o, --output <dir>` - Output directory (default: current directory)

**Examples:**
```bash
# Create a basic curriculum
scholium create my-curriculum

# Create a medical curriculum template
scholium create usmle-step1 --template medical

# Create in a specific directory
scholium create spanish-101 -t language -o ./curricula
```

**Generated structure:**
```
my-curriculum/
├── manifest.json      # Package metadata
├── curriculum.json    # Content structure with example items
└── media/             # Directory for images, audio, video
```

---

## Package Format

Scholium Curriculum Packages (`.spkg`) are ZIP archives containing:

| File | Description |
|------|-------------|
| `manifest.json` | Package metadata (name, version, provider, stats) |
| `curriculum.json` | Hierarchical content (modules → topics → items) |
| `media/` | Optional directory for images, audio, video, PDFs |

### Supported Item Types

- **Flashcards** - Front/back cards with optional explanations
- **MCQ** - Multiple choice questions with USMLE-style stems
- **Cloze** - Fill-in-the-blank questions
- **Matching** - Match items from two columns
- **Ordering** - Arrange items in correct sequence
- **Text Content** - Explanatory text blocks
- **Media** - Embedded images, audio, video

---

## Building a Package

After creating and editing your curriculum:

```bash
cd my-curriculum
zip -r ../my-curriculum.spkg manifest.json curriculum.json media/
```

Then validate before publishing:
```bash
scholium validate my-curriculum.spkg
```

---

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success (valid package, no errors) |
| 1 | Failure (invalid package, errors found, or `--strict` with warnings) |

---

## Links

- [Scholium Platform](https://scholium.app)
- [Package Format Documentation](https://scholium.app/docs/curriculum-packages)
- [Report Issues](https://github.com/scholium/scholium/issues)