Quickstart

1. Install the CLI

Install with Bun, then check that the command is available. Local scaffolding, validation, and review work without an account.

bun add -g @graspful/cli
graspful --help

To configure tools in your AI agent, follow the MCP setup guide. Give PDFs, notes, and official references to that external agent. It reads your source and writes the YAML on your computer.

2. Plan and author the course

Start with an official syllabus, handbook, or other source you can verify. Record its version and the intended learner. Follow the course creation guide to plan the academy, course boundaries, and prerequisite graph before you write lessons.

Create a local draft

# Replace the topic and source with your course details.
graspful create academy --topic "Your Topic" -o academy.yaml
graspful create course \
  --topic "Your Topic" \
  --source "Official source title, edition, and year" \
  --hours 10 \
  -o course.yaml

The scaffold is an unfinished draft. It contains a starting graph with empty concepts and cannot pass the publication review. Edit the academy manifest to reference the course files you plan to include.

Write the learning content

# "Your Topic" creates the initial concept ID "your-topic-intro".
# Use an ID from your own YAML after editing the graph.
graspful fill concept course.yaml your-topic-intro --kps 3 --problems 4
graspful describe course.yaml

The fill command adds TODO stubs. You or your external AI agent must replace each stub with a lesson, a worked example, and distinct practice problems with correct answers and explanations. Repeat for each concept. Compare the completed content with your source.

3. Validate and review

graspful validate course.yaml
graspful review course.yaml

Fix each failure and run both commands again. A score of 10/10 means the automated checks passed. You still need to review source accuracy, answer keys, teaching quality, and course coverage before publishing. Read the review gate reference for the checks and their limits.

4. Register before importing

graspful register --email you@example.com

The CLI opens browser authentication and saves an API key locally when you finish. Use the organization slug returned by registration in place of my-org below. Keep your API key private.

5. Import as a draft

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

The default import creates a draft. Save the returned courseId and URL. The response should report published: false for a new draft. You can also import the academy manifest and its course files with the command below.

# Use this for an academy after reviewing all referenced course files.
graspful import academy.yaml --org my-org --course-dir . --format json

6. Publish and confirm the result

# Replace <course-id> with the courseId returned by import.
graspful publish <course-id> --org my-org --format json

The server runs the review gate again. Confirm that the response reports published: true before you share the course. If publication fails, read the reported failures, correct the YAML, run validation and review, and replace the draft before retrying.

# After correcting and reviewing the local file:
graspful import course.yaml --org my-org --replace --format json
graspful publish <course-id> --org my-org --format json

Open the URL returned by import and test a lesson and an incorrect answer as a learner. For an academy, confirm publication for every course you intend to offer. The optional --publish import flag requests publication during import; check its returned state too.

Add a branded landing page

Use a brand YAML to configure the landing page, theme, and domain. Write copy that describes the actual lessons and learner. Confirm domain verification after import. Paid access also requires completed billing setup. See the brand schema and billing guide.