CLI

Build documents and track CLI versions

Run complete document builds and distinguish CLI, server, browser, and agent-skill versions.

Build a saved document through CoCalc

project build runs the project's document pipeline without an open browser. Use it for .tex, .Rnw, .Rtex, .Rmd, and .qmd sources. For example, a LaTeX build can include required SageTeX or PythonTeX stages; one standalone compiler invocation does not necessarily verify the complete document.

Use the profile and project ID from the quickstart. Save any collaborative edits first, and replace DOCUMENT_PATH with the source path inside the project:

export CLI_PROFILE=cocalc-ai
export PROJECT_ID='REPLACE_WITH_FULL_PROJECT_ID'
export DOCUMENT_PATH='/home/user/paper.tex'

cocalc project build --help
cocalc --profile "$CLI_PROFILE" --json --timeout 20m \
  project build "$DOCUMENT_PATH" --project "$PROJECT_ID" \
  --build-timeout 15m

The server's capability response determines the supported formats. The command waits by default. Require successful command completion, ok:true, data.state:"succeeded", and data.wait_timed_out:false; then inspect data.artifacts, diagnostics, and the generated document.

The global --timeout limits how long this CLI invocation waits. Expiry does not cancel the build. --build-timeout sets the project-side whole-build deadline. A failed build returns a nonzero exit status even in JSON mode; a local wait timeout or timed-out build uses 124, and cancellation uses 130.

--detach submits without waiting and returns a build_id; this is not proof of success. The current CLI exposes submission through project build, but no companion build get/wait/cancel subcommands. Do not pass a build ID to op wait or invent project build status. For unattended verification, prefer the wait-for-completion invocation above. After an uncertain response, inspect the project's build state before starting another build.

Know which version supplies each interface

Surface	Source of its behavior or content
`cocalc --help`, subcommand help	Installed CLI build.
`cocalc docs search/show/skill-context`	Documentation bundled with that CLI.
`cocalc exec-api`	Backend API declaration bundled with that CLI.
`cocalc browser exec-api`	Selected running browser session and its policy.
Project operations and build capabilities	Running project/server services.
CoCalc-provided agent skills	The applicable project-host runtime, unless locally overridden.

When a documented command is absent, record cocalc --version and inspect its help. A website update does not change docs already bundled in an installed CLI, and updating the CLI does not refresh a stale browser session.

cocalc --version
cocalc docs list --category CLI
cocalc exec-api
cocalc docs skill-context --query "notebook"

docs skill-context prints selected docs; it does not install or update a skill. In the managed Launchpad project runtime, built-in skills are mounted read-only unless a project-local directory under .codex/skills/<skill-name> overrides that skill. This applies to the managed runtime path, not every way of running an agent or CLI. A local override can remain older than the supplied skill. Review overrides deliberately rather than deleting them during a routine CLI update.

Report a reproducible problem

Include the installed version, relevant command help, selected project/browser context, exact sanitized command, and the result checks you applied. Distinguish:

A command or option missing from the installed CLI.
Authentication or target-resolution failure.
A server capability or policy denial.
An operation accepted but failing later.
Successful execution with incorrect document or UI results.

Keep credentials and private document contents out of shared logs. For JSON and recovery examples, use scripting and results. For live source changes, maintainers should follow the repository's docs/cli-guide-validation.md and record what actually ran.