witwin CLI

Reference for the witwin command - init, check, run, open, add, platform, solve and host - with every option.

witwin works with a Project without the editor. It is installed by the witwin-studio package and can also run as python -m witwin.studio. Most commands find the Project by walking up from the current folder to the nearest witwin.toml.

witwin init #

witwin init [path] [--name NAME]

Makes a folder a Project and a Python project. In a new or empty folder it writes witwin.toml, pyproject.toml, README.md, .gitignore and .gitattributes, runs git init and makes the first commit. It never overwrites an existing file: an existing pyproject.toml only gains the witwin-studio dependency, an existing .gitignore only gains .witwin/ and .venv/.

pathfolderdefault current folder

Folder to initialize.

--namestring

Project display name.

witwin check #

witwin check [path]

Validates the Project files. Exits non-zero on errors, so it fits in CI.

witwin run #

witwin run [--project PATH] script [args ...]

Runs a Python script with the Project root and the script's folder on sys.path. Arguments after the script are passed to it.

--projectfolderdefault the Project holding the script

Project folder.

witwin open #

witwin open [path]

Opens the Project in WiTwin Studio.

witwin add #

witwin add SPEC [--project PATH] [--tag TAG | --rev SHA | --branch NAME]
           [--no-editable] [--index-url URL] [--uv PATH] [--python PATH]
           [--no-sync] [--json]

Adds a Plugin dependency to pyproject.toml and syncs the Project's environment with uv. Plugins come from the witwin index, a git URL or a folder, never from PyPI. If the sync fails, pyproject.toml and uv.lock are restored.

SPECstringrequired

A requirement ("wt-radar>=0.3"), a git URL (git+https://...) or a folder.

--tag / --rev / --branchstring

Git ref for a git URL. Use one.

--no-editableflag

Install a folder as a regular package instead of editable.

--index-urlurldefault the published witwin index

witwin index to use.

--uvpathdefault WITWIN_UV, the uv package, then PATH

uv executable.

--pythonpath

Interpreter for a new .venv.

--no-syncflag

Edit pyproject.toml and uv.lock only.

--jsonflag

Print JSON lines on stdout.

witwin platform #

witwin platform [path] [--write] [--json]

Compares the Project's lock with the cloud platform's pinned packages.

--writeflag

Write the platform constraints into pyproject.toml.

--jsonflag

Print one JSON object on stdout.

witwin solve #

witwin solve [SOLVER] [--project PATH] [--scene ID] [--config FILE]
             [--set KEY=VALUE ...] [--plugin-path PATH ...]
             [--attach | --no-attach] [--no-record] [--list] [--json] [--quiet]

Runs a Plugin solver headless and records a Result. When Studio has the Project open, the run goes to that server unless you pass --no-attach.

SOLVERstring

Solver id, for example witwin.radar.simulate.

--scenestringdefault the main scene

Scene id.

--configfile

Solver config file (.toml or .json).

--setKEY=VALUE

One config value, JSON or text; dotted keys nest. Repeatable.

--plugin-pathfolder

Extra local Plugin folder. Repeatable.

--attachflag

Require a running Project server.

--no-attachflag

Never use a running Project server.

--no-recordflag

Do not write a Result.

--listflag

List the solvers this Project can run.

--jsonflag

Print one JSON object on stdout.

--quietflag

Hide solver log lines.

witwin host #

witwin host [path] [--headless] [--no-relay] [--attach URL] [--init]
            [--allow-broad-folder] [--port N] [--plugin-path PATH ...]
            [--no-plugins] [--verbose]
witwin host status [path]
witwin host unregister [path]
witwin login | logout | whoami

Serves a folder as a Project for My machines. Provided by the WiTwin server package. See Connect your own machine.

Commands from other packages #

Installed packages can add subcommands through the witwin.cli entry point group. Built-in command names always win.