@chalksurf/cli

Publishable ChalkSurf CLI package. Expect breaking changes while the CLI is still only used internally.

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:

CHALKSURF_TOKEN=cs_cli_... \
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 \
  --patch-json '{"translations":{"english":{"exercise_text":"Find $x^2$."}}}' \
  --json

Sheet import manifests use top-level sheets[], where each sheet has one targetFolderPath and one or more ordered sources[]. See the canonical example.

Docs

• Manual operator guide
• Agent and Codex guide
• MCP guide
• Manifest reference
• Exit codes and JSON errors
• Sheet import schema
• Exercise import schema
• Exercise solution import schema
• Exercise sheet solution 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