TutorFlow CLI Overview

After this page an agent or a CI job can install @tutorflow/cli, give it a key, pick the classroom it works in, and script it with JSON output.

What the TutorFlow CLI Does

The TutorFlow CLI (@tutorflow/cli, executable tutorflow) wraps the Content API and the Agent Platform account routes in shell commands. AI agents, CI jobs, and local scripts can use it to generate courses, slide decks, tests, modules, videos, games, and simulations, grade learner answers, manage learners and webhooks, and handle registration and billing, without writing an HTTP client.

This page describes version 0.5.0. Content commands call /v1/content/classrooms/{classroomId}/... with a tf_content_ key. Account and discovery commands call /v1/platform/agent/*, /v1/platform/health, /v1/platform/pricing-catalog, and /v1/platform/.well-known/agent.json.

Install @tutorflow/cli

The CLI needs Node.js 18 or later.

Run it without a global install:

Running tutorflow with no arguments prints the help and exits with status 1.

Authenticate the CLI

The CLI takes a tf_content_ key. You get one in either of two ways:

• tutorflow agent register creates an agent account and saves the returned contentApiKey to the local config. See Agent Account and Billing CLI.
• Create a key in the Agent Platform dashboard, then save it:

tutorflow auth login --api-key tf_content_...
tutorflow auth whoami

auth whoami makes no network call. It shows the masked key, its kind, the base URL, and whether the key came from the environment or the config file. Use tutorflow platform health to check that the API accepts the key.

The CLI sends the key as Authorization: Bearer <apiKey>. auth login without --api-key reads TUTORFLOW_API_KEY, or prompts for the key on a terminal. auth logout deletes the config file; it asks for confirmation, or takes --force in non-interactive mode.

Choose the Classroom

Every content command acts in one classroom. The CLI picks it in this order, first match wins:

1. The global --classroom <id> flag.
2. TUTORFLOW_CLASSROOM_ID.
3. classroomId in the config file (tutorflow config set classroomId <id>).
4. GET /v1/platform/agent/account: sandboxClassroomId for a test key, defaultClassroomId otherwise.
5. GET /v1/content/classrooms, when the account route refuses the key: the only classroom the key reaches, or the sandbox classroom for a test key. If the key reaches several, the command exits with status 2 and code ECLASSROOM and lists them.

tutorflow classroom list shows the classrooms the key can reach. Pinning a classroom with --classroom or TUTORFLOW_CLASSROOM_ID also saves the account lookup on every call.

Configuration

The config file is ~/.tutorflow/config.json, written with mode 0600.

tutorflow config get
tutorflow config get classroomId
tutorflow config set baseUrl https://api.tutorflow.io

Environment variables win over the config file. An empty variable counts as unset.

Use JSON and Non-Interactive Mode

Put --json before or after the subcommand:

tutorflow --json platform pricing
tutorflow course list --json

In JSON mode:

• Each result is one JSON line on stdout. The examples in these docs are pretty-printed.
• Errors are one JSON line on stderr.
• Status and progress lines are not printed.
• The CLI never prompts. A missing argument fails with ENOINTERACTIVE, and delete and remove commands need --yes.

Without a terminal, the CLI does not prompt either.

Example error output in JSON mode:

{
  "error": {
    "message": "API error 402 content_payment_required: <message from the API>",
    "code": "EHTTP_402",
    "status": 402,
    "apiCode": "content_payment_required",
    "requestId": "req_...",
    "hint": "Add credits: `tutorflow agent billing session` (needs a verified email) or `tutorflow agent billing x402-deposit --amount-usd <n>`. Check the balance with `tutorflow credits balance`."
  }
}

API errors use the code EHTTP_<status> and can carry apiCode, requestId, retryAfterSeconds, requiredScope, validation, and hint. Other codes the CLI sets itself include EAUTH (no key), EINVAL (a bad flag or argument), ENETWORK, ECLASSROOM, EPLATFORMKEY, ETIMEOUT, and ERUNFAILED.

TutorFlow CLI Command Groups

Changes in 0.5.0

• New on every content resource: share <id>, which makes it open by link and prints publicUrl, and visibility <id> <value>. See Commands Every Resource Shares.
• video create --visibility also takes UNLISTED.

Changes in 0.4.0

0.4.0 moved the content commands from the removed /v1/platform content routes to the Content API. If you used 0.3.x:

• Content commands need a tf_content_ key; a tf_platform_ key fails with EPLATFORMKEY. agent register now saves contentApiKey.
• course, slide, test, and module use generate (alias create), which returns a run. Add --wait to get the finished resource.
• Flags changed: course generate --lessons is now -n (-l is --language), slide generate --theme takes a theme id, and module and test lost the 0.3 options such as --title, --target, --locale, --private, --no-quiz, --classroom-id, --tier, --mode, and --time-limit. Use the global --classroom instead of --classroom-id.
• video create takes --title and one --scene <script> per scene instead of a prompt with --scenes, --ratio, and --duration. Render with video render --generate-missing-narration --wait.
• Removed: test edit-token, the --open flag on create, and --offset and --status on list. Use open <id> for the editor and public URLs, and --page and --search on list.
• New: classroom, run, game, simulation, evaluation, learner, webhook, credits, video scene, video narrate, video render, delete on every resource, agent billing x402-deposit, platform share-redirect, and the global --classroom.