CLI Reference

The @graspful/cli package provides a complete command-line interface for creating, validating, reviewing, and publishing adaptive learning courses.

Global option: All commands support --format <human|json> to control output format. Default is human. Use --format json for machine-readable output in automated workflows.

graspful login

Authenticate with a Graspful instance. Saves credentials locally for subsequent commands. In interactive mode, prompts for an API key. Supports piped input for CI.

graspful login [--api-url <url>] [--token <token>]

Options

--api-url <url>	API base URL (defaults to https://api.graspful.com)
--token <token>	API key or JWT token (skips interactive prompt)

Interactive login

graspful login

Non-interactive

graspful login --token gsk_abc123

# Or pipe from a secret manager
vault read -field=token secret/graspful | graspful login

JSON output

{
  "authenticated": true,
  "baseUrl": "https://api.graspful.com"
}

graspful validate

Validate a course, brand, or academy YAML file against its Zod schema. Auto-detects the file type from the top-level key (course, brand, or academy). For course files, also validates the prerequisite DAG — checking for missing references and cycles.

graspful validate <file>

Validate a course

graspful validate my-course.yaml

Validate a brand

graspful validate my-brand.yaml

JSON output for CI

graspful validate my-course.yaml --format json

JSON output

{
  "valid": true,
  "fileType": "course",
  "errors": [],
  "stats": {
    "fileType": "course",
    "concepts": 42,
    "knowledgePoints": 120,
    "problems": 360
  }
}

graspful create course

Generate a course YAML scaffold with sections, concepts, and prerequisite edges. The scaffold contains no learning content — just the graph structure with TODO placeholders. Edit the output to add concepts, adjust prerequisites, and set difficulty levels before filling.

graspful create course \
  --topic <topic> \
  [--hours <hours>] \
  [--source <source>] \
  [-o, --output <file>] \
  [--scaffold-only]

Options

--topic <topic>	Course topic name (required)
--hours <hours>	Estimated total course hours (default: 10)
--source <source>	Source document reference (e.g., textbook, exam guide)
-o, --output <file>	Output file path (defaults to stdout)
--scaffold-only	Generate scaffold without AI enrichment (default: true)

Scaffold to stdout

graspful create course --topic "Linear Algebra"

Scaffold to file with source

graspful create course \
  --scaffold-only \
  --topic "AWS Solutions Architect" \
  --source "AWS SAA-C03 Exam Guide" \
  --hours 40 \
  -o aws-saa-c03.yaml

graspful fill concept

Add knowledge point (KP) and problem stubs to a specific concept in a course YAML file. Each KP includes instruction text, a worked example, and multiple-choice problems with a difficulty staircase. Fails if the concept already has KPs to prevent accidental overwrites.

graspful fill concept <file> <conceptId> \
  [--kps <count>] \
  [--problems <count>]

Options

<file>	Path to the course YAML file
<conceptId>	ID of the concept to fill (must have 0 KPs)
--kps <count>	Number of KP stubs to add (default: 2)
--problems <count>	Number of problem stubs per KP (default: 3)

Fill with defaults

graspful fill concept aws-saa-c03.yaml vpc-basics

Custom stub counts

graspful fill concept aws-saa-c03.yaml iam-policies --kps 3 --problems 4

JSON output

{
  "conceptId": "vpc-basics",
  "kpsAdded": 2,
  "problemsPerKp": 3,
  "file": "aws-saa-c03.yaml"
}

graspful review

Run all 10 mechanical quality checks on a course YAML. Returns a score (e.g., 8/10) with details on each failure. A score of 10/10 is required for publishing. See the Review Gate docs for details on each check.

graspful review <file>

Run review

graspful review my-course.yaml

JSON output

graspful review my-course.yaml --format json

JSON output

{
  "passed": false,
  "score": "8/10",
  "failures": [
    {
      "check": "difficulty_staircase",
      "passed": false,
      "details": "\"vpc-basics\" has problems at only 1 difficulty level(s) — need 2+"
    },
    {
      "check": "worked_example_coverage",
      "passed": false,
      "details": "1/5 authored concepts have worked examples (20%) — need 50%+"
    }
  ],
  "warnings": [],
  "stats": {
    "concepts": 42,
    "kps": 10,
    "problems": 30,
    "authoredConcepts": 5,
    "stubConcepts": 37
  }
}

graspful import

Import a course or brand YAML into a Graspful organization. Auto-detects the file type. For courses, use --publish to publish immediately — this runs the review gate server-side. If review fails, the course is imported as a draft with failure details.

graspful import <file> \
  --org <slug> \
  [--publish]

Options

<file>	Path to the YAML file (course or brand)
--org <slug>	Organization slug (required for courses)
--publish	Publish immediately after import (runs review gate)

Import course as draft

graspful import my-course.yaml --org my-org

Import and publish

graspful import my-course.yaml --org my-org --publish

Import a brand

graspful import my-brand.yaml

JSON output

{
  "courseId": "abc-123",
  "url": "https://app.graspful.com/courses/abc-123",
  "published": true
}

graspful publish

Publish a draft course (sets isPublished = true). The server runs the review gate — the course must pass all 10 quality checks.

graspful publish <courseId> --org <slug>

Options

<courseId>	The course ID (UUID) to publish
--org <slug>	Organization slug (required)

Publish a course

graspful publish abc-123 --org my-org

JSON output

{
  "courseId": "abc-123",
  "published": true
}

graspful describe

Show course statistics and structure summary. Useful for tracking progress during authoring — how many concepts are authored vs stubs, how deep the prerequisite graph is, and what still needs content.

graspful describe <file>

Describe a course

graspful describe aws-saa-c03.yaml

JSON output

{
  "courseName": "AWS Solutions Architect",
  "courseId": "aws-saa-c03",
  "version": "2026.1",
  "estimatedHours": 40,
  "concepts": 42,
  "authoredConcepts": 5,
  "stubConcepts": 37,
  "knowledgePoints": 10,
  "problems": 30,
  "graphDepth": 6,
  "conceptsWithoutKps": 37,
  "kpsWithoutProblems": 0,
  "sections": [
    {
      "section": "foundations",
      "concepts": 12,
      "kps": 4,
      "problems": 12
    }
  ]
}

graspful create brand

Generate a brand YAML scaffold for a white-label learning site. Niche presets (education, healthcare, finance, tech, legal) set appropriate colors, taglines, and landing page copy.

graspful create brand \
  --niche <niche> \
  [--name <name>] \
  [--domain <domain>] \
  [--org <slug>] \
  [-o, --output <file>]

Options

--niche <niche>	Brand niche: education, healthcare, finance, tech, or legal (required)
--name <name>	Brand name (default: "{Niche} Academy")
--domain <domain>	Custom domain (default: "{slug}.graspful.com")
--org <slug>	Organization slug to associate with
-o, --output <file>	Output file path (defaults to stdout)

Generate a tech brand

graspful create brand \
  --niche tech \
  --name "AWS Prep Academy" \
  --domain aws-prep.graspful.com \
  --org my-org \
  -o aws-prep-brand.yaml