@chalksurf/cli

ChalkSurf CLI 0.4.0 provides content generation, imports, updates, saved plans and recoverable job controls. This release intentionally breaks older command and manifest formats; see the migration guide.

Installation

Run the published CLI without a global install:

npx @chalksurf/cli --help

Install it globally when you want a persistent local binary:

npm install -g @chalksurf/cli
chalksurf --version

Quick Start

Interactive operator flow:

chalksurf auth login --profile prod-cztamas --base-url https://chalksurf-api.fly.dev
chalksurf profile use prod-cztamas
chalksurf org list
chalksurf sheet import ./fixtures/algebra.pdf --wait

Headless or agent flow:

printf '%s' "$CHALKSURF_TOKEN" | npx @chalksurf/cli auth login \
  --profile prod-codex \
  --base-url https://chalksurf-api.fly.dev \
  --with-token

npx @chalksurf/cli --profile prod-codex sheet import --manifest - --wait --json < import.json

Agentic edit flow:

npx @chalksurf/cli --profile prod-codex sheet issues SHEET_ID --json
npx @chalksurf/cli --profile prod-codex sheet copy SHEET_ID "Easier variant" \
  --exercise-copy-mode copy_all_exercises \
  --json
npx @chalksurf/cli --profile prod-codex exercise update EXERCISE_ID \
  --target-sheet-id COPIED_SHEET_ID \
  --expected-updated-at 2026-01-01T00:00:00.000Z \
  --input - --json <<'JSON'
{"translations":{"english":{"exercise_text":"Find $x^2$."}}}
JSON

Admin sheet-series labeling:

npx @chalksurf/cli --profile prod-codex sheet list --all --result-file inventory.json --json
npx @chalksurf/cli --profile prod-codex sheet series list --subject math --json
npx @chalksurf/cli --profile prod-codex sheet update \
  --manifest batch-001.json --dry-run --plan-out batch-001.plan.json --json
npx @chalksurf/cli --profile prod-codex plan apply batch-001.plan.json --result-file applied.json --json

Review the saved plan before applying it. If the apply response is uncertain, use plan verify batch-001.plan.json and inspect request acceptance before considering another write. --input FILE|- supplies one patch; --manifest FILE|- supplies a strict v1 repeated request. See content operations for the complete generation, translation, import and recovery flow.

Every operational command accepts --result-file PATH. The CLI preflights a new destination before command execution, writes the complete success or failure JSON envelope to a private file, and refuses to overwrite existing evidence. Stdout stays compact and includes the absolute result path. If publication fails after the command finishes, stdout contains the complete envelope plus a warning and the command keeps its original exit code.

Content manifests use schemaVersion: "v1", operation and items[]. Sheet entries retain ordered sources, components or authoritative language groups. File paths resolve relative to the manifest file; stdin paths use the invocation directory. See the manifest reference and canonical examples.

Docs

• Public CLI and MCP documentation
• Manual operator guide
• Agent and Codex guide
• MCP guide
• Content operations and saved plans
• 0.4.0 migration guide
• Manifest reference
• Exit codes and JSON errors
• Sheet import schema
• Exercise import schema
• Exercise solution import schema
• Exercise sheet solution import schema
• Exercise sheet translation import schema

Local And Staging Testing

Use separate profiles so local, staging, production, human, and agent tokens do not overwrite each other:

npm run cli-dev -- auth login --profile dev-cztamas --base-url http://localhost:3101
npm run cli-dev -- profile use dev-cztamas
npm run cli-dev -- auth status --json
npm run cli-dev -- sheet import ./fixtures/algebra.pdf --wait --json

npm run cli-dev -- auth login --profile staging-codex --base-url https://chalksurf-api-staging.fly.dev
npm run cli-dev -- --profile staging-codex auth status --json
npm run cli-dev -- --profile staging-codex sheet import https://example.com/worksheet.docx --single-sheet --target-folder Imported --json