CLI Reference

Use the AI agent or desktop for everyday tasks. The CLI starts services, connects clients and inspects saved records. Consult --help in your installed version for exact arguments.

Installed Mac App commands

The bundled App supplies these entry points; no shell activation is required:

"/Applications/CulsmaOS Preview.app/Contents/MacOS/culsma-status"
"/Applications/CulsmaOS Preview.app/Contents/MacOS/culsma-stop"

Use culsma-mcp from the same directory in your AI client. The general culsma-os commands below assume a separate Python installation and the matching 0.2.0 source checkout; see Install and Start.

Commands

Command	Purpose
desktop	Open the native desktop, starting a local resident or attaching to an existing socket.
mcp	Expose a stdio MCP service to an external AI client.
serve	Start a persistent resident.
host-status / device-status	Read service and device records.
submit / runs / status	Submit a program, list runs or inspect one run.
pause / resume / cancel	Request run control.
setup	Access the loading plan and operator preparation flow from the command line.
host-stop	Request resident shutdown.
run	Execute once in the foreground; does not automatically attach to a resident.
driver-run	Direct driver diagnostics, separate from the complete OS execution path.
console	Local console HTTP service entry. This manual uses the native desktop as the user interface.

Inspect and stop the example workstation

From the OS source directory, using the runtime environment:

culsma-os host-status --socket "$PWD/run-artifacts/manual-desktop/station.sock"
culsma-os runs --socket "$PWD/run-artifacts/manual-desktop/station.sock"
culsma-os status RUN_ID --socket "$PWD/run-artifacts/manual-desktop/station.sock"

After checking that runs have been handled, request shutdown:

culsma-os host-stop --socket "$PWD/run-artifacts/manual-desktop/station.sock"

Replace RUN_ID with the actual returned identifier. Stopping the service does not delete run records or reset station state.

Run a separate CLI simulation

Use an independent simulated station. Do not create another controller competing for the desktop resident's station:

export CULSMA_OS_STATION_ROOT="$PWD/run-artifacts/manual-cli-stations"
culsma-os run examples/transfer/transfer.culs \
  --station-id manual-cli-transfer \
  --driver-config examples/transfer/deck.json \
  --host-db run-artifacts/manual-cli/os.sqlite3 \
  --artifacts-dir run-artifacts/manual-cli

In this example's output directory, result.json contains the OS outcome and run.json contains runtime state and material records. The specified SQLite database stores runs and checkpoints. Do not assume these files have the same roles as similarly named outputs from the independent language CLI.

Inspect command options

culsma-os desktop --help
culsma-os mcp --help
culsma-os setup --help

See Install and Start and Connect Your AI Agent for the launch arguments and matching paths.