Content Generation CLI

Use this page to look up every CLI command that generates, reads, or deletes content, follows runs, and grades answers.

These commands call the Content API at /v1/content/classrooms/{classroomId}/... and need a tf_content_ key. Each one acts in the classroom chosen as described in Choose the Classroom; pass the global --classroom <id> to pick one. webhook and credits act on the organization, not a classroom.

The commands on this page describe @tutorflow/cli 0.5.0. Run tutorflow <command> --help for the flags of your installed version.

Commands Every Resource Shares

course, slide, test, module, video, game, and simulation each have these subcommands:

share and visibility send PATCH with visibility, or isPublic for a module:

publicUrl stays null until a video is rendered, a game or simulation is built, or a course is published, and always in the sandbox classroom of a test key. In text mode share says which applies. A value the resource does not take exits 2 with EINVAL before any request.

tutorflow course list --search python --limit 50
tutorflow --json slide get 00000000-0000-4000-8000-000000000301
tutorflow test delete 00000000-0000-4000-8000-000000000401 --yes
tutorflow --json video share 00000000-0000-4000-8000-000000000601 | jq -r .publicUrl

In text mode, list prints a table of ID, title, status, and the updated date. In JSON mode it prints the API page as returned.

Generate Courses, Slides, Tests, and Modules

course, slide, test, and module have generate [prompt], with the alias create. The prompt is the first argument. On a terminal the CLI asks for it when you leave it out; otherwise the command fails with ENOINTERACTIVE.

Flags all four share:

tutorflow course generate

Generates a course with every lesson. The CLI's help lists the price as 3 credits for the outline plus 3 per lesson.

tutorflow course generate "Beginner Python for analysts" --lessons 5 --level beginner --wait

tutorflow slide generate

Generates a slide deck with every page, charged per page.

tutorflow slide generate "Photosynthesis" --count 8 --text-length concise --wait

tutorflow test generate

Generates a test with auto-graded items (3 credits).

tutorflow test generate "Algebra basics" --items 3 --item-types select,blank,open-ended --wait

tutorflow test results <testId> lists learners' results, with -l, --limit <n> (default 20) and --cursor <cursor> (the meta.nextCursor of the previous page).

tutorflow module generate

Generates an interactive lesson module (3 credits).

tutorflow module generate "Fractions for 5th grade" --type flashcard --wait

What generate prints

Without --wait, generate prints the run the API accepted and returns at once:

{
  "runId": "00000000-0000-4000-8000-000000000b01",
  "status": "queued",
  "kind": "course",
  "estimatedCredits": 21,
  "statusUrl": "/v1/content/classrooms/00000000-0000-4000-8000-000000000010/runs/00000000-0000-4000-8000-000000000b01"
}

With --wait, the CLI polls the run every 3 seconds (set TUTORFLOW_POLL_INTERVAL_MS to change it) and prints progress to stderr in text mode. It rides out up to five transient failures in a row (network errors, 429, 5xx). When the run completes, JSON mode prints the run and the resource it made:

{
  "run": {
    "runId": "00000000-0000-4000-8000-000000000b01",
    "kind": "course",
    "status": "completed",
    "resourceId": "00000000-0000-4000-8000-000000000201",
    "creditsCharged": 18
  },
  "resource": {
    "id": "00000000-0000-4000-8000-000000000201",
    "title": "Beginner Python for analysts",
    "editorUrl": "https://...",
    "publicUrl": "https://..."
  }
}

The run and resource are abridged here. resource is null when the follow-up read fails; the run is still reported. Text mode prints runId, status, creditsCharged, resourceId, title, editorUrl, and publicUrl.

If the run fails, the command exits 1 with ERUNFAILED; for a course the hint names tutorflow run resume <runId>. If --timeout passes first, it exits 1 with ETIMEOUT, and the run keeps going: pick it up with tutorflow run wait <runId>.

See Generation Runs for the run fields, stages, and time limits.

Follow Generation Runs

tutorflow --json run wait 00000000-0000-4000-8000-000000000b01 --timeout 1800

Videos

tutorflow video create

Creates a video. Each --scene <script> adds a scene with that narration script, in order. With scenes, the command prints the video after the last scene is added; without, it prints the created video.

tutorflow video create --title "How rainbows form" \
  --scene "Sunlight looks white, but it holds every color." \
  --scene "Raindrops bend each color by a different amount."

If a scene fails, the video still exists. The error names the videoId and how many scenes were added, and the hint shows the video scene add command for the rest.

Scenes

add and update take --script <text> (narration), --display-text <text> (text on screen), and --duration <seconds>.

Narrate and render

tutorflow video render 00000000-0000-4000-8000-000000000601 --generate-missing-narration --wait

With --wait, the command prints the final render status once renderStatus is COMPLETED. A FAILED render, or one that goes back to IDLE after rendering (cancelled), exits 1 with ERUNFAILED. Completion also arrives as the video.render.completed webhook. See Video Render.

Games and Simulations

game and simulation share one flow: create, plan with brief, then build, and revise later.

brief, build, and revise take -w, --wait, --timeout <seconds> (default 900), and --idempotency-key. The CLI always asks the API for the asynchronous 202 answer, not the event stream.

tutorflow game create --title "Fraction match"
tutorflow game brief 00000000-0000-4000-8000-000000000701 --wait
tutorflow game build 00000000-0000-4000-8000-000000000701 --wait --timeout 600

With --wait, the command prints the { active, last } status once the step ends. A failed step exits 1 with ERUNFAILED. See Games and Simulations.

Evaluate Learner Answers

tutorflow evaluate

Grades one answer and waits for the result (1 credit).

tutorflow evaluate --type open-ended \
  --question "Why is the sky blue?" \
  --student-answer "Air scatters blue light more." \
  --learner-id student-7 --concept-tags light,atmosphere

On a terminal the CLI asks for a missing type, question, answer, or expected answer.

tutorflow evaluation

Learners

Learner commands need a live key; a test key gets 403 content_sandbox_unsupported.

tutorflow learner invite --email learner@example.com --course 00000000-0000-4000-8000-000000000201

An organization member joins at once; anyone else gets an invitation. See Learners.

Webhooks

Webhook commands call /v1/content/webhooks and need a key with the webhooks:manage scope.

tutorflow webhook create --url https://example.com/hooks/tutorflow \
  --event course.generation.completed --event video.render.completed

Test endpoints receive the events of test keys. See Webhooks.

Classrooms and Credits

A test key works in the sandbox classroom and spends nothing. See Test Mode.