CLI quick start

The ChalkSurf CLI is designed for both interactive operators and agents. It supports profiles, explicit organization selection, machine-readable output, and stable exit codes.

Install or run it directly

Run the published package without a global installation:

npx @chalksurf/cli@latest --help

Or install a persistent chalksurf binary:

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

The website tracks the repository version. For an installed package, chalksurf --help is authoritative.

Authenticate with a profile

Create a named profile so development, staging, production, human, and agent credentials do not overwrite one another:

chalksurf auth login \
  --profile production-agent \
  --base-url https://chalksurf-api.fly.dev
chalksurf profile use production-agent
chalksurf auth status --json

For a headless flow, provide the token over standard input rather than putting it in shell history:

printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login \
  --profile production-agent \
  --base-url https://chalksurf-api.fly.dev \
  --with-token

Select an organization explicitly

List the organizations available to the authenticated user:

chalksurf org list --json

Then either set a profile default or pass --organization ORGANIZATION_ID to an individual command. Agents should not infer an organization from a resource ID.

Verify a read before writing

chalksurf --profile production-agent sheet search --query algebra --json
chalksurf --profile production-agent sheet get SHEET_ID --json

Use current updated_at values and exact confirmation arguments when a write command requires them. Keep --json enabled for automation and inspect both the envelope and process exit code.

Continue with the generated CLI reference or review exit codes and JSON errors.