Skip to main content

Command Line and Environment

A simulation built with CppModel is an ordinary program. It needs no separate command-line tool: the program itself takes the options below, reads the environment variables below and reports its result in its exit code, so CI jobs and scripts run it directly.

Simulation options​

Every simulation accepts these options, whether it is written in C, C++, Python or JavaScript. The library reads them from the process itself, so your main() doesn't need to pass them on. See Local runs.

OptionEffect
--inputs <file>Takes the inputs and parameters from the file (- for stdin) instead of the workspace.
--results <file>Writes the execution to the file (- for stdout) instead of recording it in the workspace. Refused when CI is set.

Both together make a local run: nothing is fetched or recorded.

./build/FirstSimulation --inputs candidate.json                     # recorded, with these values
./build/FirstSimulation --inputs candidate.json --results out.json # a local run
python heater.py --inputs candidate.json # the same for Python and Node.js

Documentation upload options​

A program made with CMODEL_DOCUMENT() takes its own options. See Publishing Documentation.

OptionEffect
--project <name>Required. The documentation project in your workspace.
--docs <folder>Required. The documentation folder.
--checkChecks the folder only: nothing is uploaded and no sign-in is needed.
--helpPrints the usage.

Environment variables​

VariableEffect
CPPMODEL_USERNAME, CPPMODEL_PASSWORDLog in with these credentials instead of the browser login. Use them in scripts and CI.
CPPMODEL_LOGIN_TIMEOUTHow many seconds to wait for the browser login (default 60). 0 fails right away instead of printing a login link, which is what you want in CI.
CPPMODEL_WORKSPACEThe workspace to use when your account belongs to more than one, for example w12345. By default it comes from your account.
CPPMODEL_ACCESS_TOKENAn access token for a single run, for example one handed over by the CppModel MCP server. It takes precedence over the saved login and the credentials while it is valid, and is never stored.
CPPMODEL_REQUIREMENTS_FILEWhere the requirements a run verified are written, instead of cppmodel-requirements.json in the working directory. See Requirements.
CIWhen set (and not 0 or false), --results is refused, so CI runs always record their executions.

The login is saved in .cppmodeltoken in the directory the program runs from, after a browser sign-in. Keep it out of version control.

When the workspace rejects a login that has expired in the meantime, for example during a long series of runs, the library gets a new one from the saved login or the credentials and sends the request again. Recording an execution is retried for about 10 seconds when the connection fails.

Exit code​

ProgramExit code
A simulation made with CMODEL_SIMULATE, or whose main() returns its result0 when every step passed and the run was recorded. Otherwise the CppModel.Step of the first failing step, or a non-zero value when the run couldn't start, for example without a login.
A documentation upload made with CMODEL_DOCUMENT()0 when the check, and the upload, passed, otherwise 1.

Scripting the workspace​

To read results, compare executions, set the inputs and parameters for the next run, or run a simulation over many parameter values, use the CppModel MCP server from Claude Code or another AI assistant, or the workspace at workspace.cppmodel.com.

For a parameter sweep in CI, run the simulation once per case with --inputs <case.json>. Each run is recorded with its values, and its exit code says whether it passed.