@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

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
• 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