pythonide-cli

Mini App Live Preview CLI for editing PythonIDE iOS projects on desktop.

Quick start

Run this command in your desktop project directory:

npx pythonide-cli start

Then open PythonIDE on iPhone or iPad:

Tools > Mini App Preview / Mini App 预览

Scan the QR code shown in the terminal, or connect from Bonjour discovery after the computer is trusted. PythonIDE syncs the selected App project into a desktop workspace, opens your editor, runs the entry file immediately, and refreshes the Mini App/AppUI preview whenever VS Code auto-saves.

Do not run PythonIDE-only scripts with desktop python3. Modules such as widget, ui, and pythonide run inside the PythonIDE iOS runtime. The desktop CLI is the sync, diagnostics, and live-preview bridge.

Simulator preview

For a real iOS Simulator preview on Mac:

npx pythonide-cli preview

This boots an iOS Simulator, builds and installs PythonIDE, opens the Mini App preview connection, syncs the workspace, opens VS Code, and tries to place VS Code and Simulator side by side. After that, VS Code auto-save syncs files back into the real PythonIDE iOS runtime and refreshes the preview.

For local development before publishing:

npm install
npm run dev

Included features

• Bonjour local-network discovery
• QR-code connection with a one-time token
• App project snapshot sync to the desktop working directory
• Desktop file watching
• Save-on-desktop sync back to the app
• Auto-preview on connection and on save
• Multi-entry run configuration
• Binary file sync with size limits and SHA-256 verification
• SHA-256 verification and atomic writes for safer file sync
• Auto-run entry file on the iOS device for live Mini App/AppUI preview
• stdout/stderr/traceback streaming back to the terminal
• Pyright/Pylance workspace setup with type checking off by default to avoid false-positive red squiggles in dynamic Mini App/AppUI code
• Generated .pyi stubs for PythonIDE dynamic modules
• Generated VS Code/Pylance settings for PythonIDE stubs such as appui
• Auto-open VS Code first, then Cursor, Zed, WebStorm, or Finder when available
• .pythonideignore rules on the desktop watcher

VS Code companion

With normal VS Code, saving a Python file in the synced workspace sends it back to PythonIDE and reruns the selected entry file on the iPhone/iPad runtime. The CLI also writes .vscode/tasks.json and .vscode/launch.json, so VS Code can run the active file through PythonIDE instead of desktop Python:

• Terminal > Run Task > PythonIDE: Run Current File on iPhone
• Run and Debug > PythonIDE: Run Current File on iPhone

For manual Run/Stop commands inside VS Code, launch or install the companion extension:

• PythonIDE status bar item
• editor title Run/Stop buttons for .py files
• CodeLens actions above Python files
• PythonIDE: Run on iPhone
• PythonIDE: Stop on iPhone
• PythonIDE: Run Pyright Diagnostics
• VS Code Problems integration for Pyright diagnostics
• PythonIDE Output channel for device stdout/stderr, sync, run, and traceback events
• Running the current active .py file when it is inside the synced workspace

If you accidentally click VS Code/Python's local "Run Python File" button on a Mini App script, PythonIDE-generated workspace settings point iOS-only imports such as appui, ui, and widget at a local forwarder. The forwarder sends the current file to PythonIDE instead of trying to run it with desktop Python. If the workspace has not connected to the app yet, it prints a short setup message instead of ModuleNotFoundError.

Options

npx pythonide-cli start --port=4000
npx pythonide-cli start --strict-port
npx pythonide-cli start --host=0.0.0.0
npx pythonide-cli start --editor=code
npx pythonide-cli start --editor=cursor
npx pythonide-cli start --editor=vscode-extension
npx pythonide-cli preview
npx pythonide-cli start --simulator --editor=vscode-extension
npx pythonide-cli simulator --project-dir=./MobileProjects
npx pythonide-cli start --simulator --simulator-name="iPhone 16 Pro"
npx pythonide-cli start --simulator --simulator-udid=<UDID>
npx pythonide-cli start --simulator --app-bundle="/path/to/Python IDE.app"
npx pythonide-cli start --simulator --no-simulator-auto-sync
npx pythonide-cli start --simulator --no-preview-layout
npx pythonide-cli start --project-dir=./MobileProjects
npx pythonide-cli start --max-file-mb=50
npx pythonide-cli vscode --workspace=./MobileProjects
npx pythonide-cli run ./main.py
npx pythonide-cli stop
npx pythonide-cli diagnostics
npx pythonide-cli start --type-checking=basic
npx pythonide-cli start --type-checking=strict
npx pythonide-cli start --no-bonjour
npx pythonide-cli start --no-pyright
npx pythonide-cli start --no-stubs
npx pythonide-cli start --no-open

Default ignored paths include .git/, .venv/, venv/, node_modules/, __pycache__/, .pytest_cache/, .mypy_cache/, site-packages/, .DS_Store, .pythonide/, and .pythonide-dev.json.

Real iOS Simulator preview

The Simulator mode intentionally uses the real PythonIDE app runtime, not a web preview. Internally it uses Apple's xcodebuild and xcrun simctl:

1. Select or boot an available iOS Simulator.
2. Build the configured Xcode scheme for iphonesimulator, unless --app-bundle points at a prebuilt .app.
3. Install the app with xcrun simctl install.
4. Launch PythonIDE with xcrun simctl launch and pass the Mini App preview URL through --pythonide-desktop-dev-url, avoiding Simulator URL-confirmation prompts.
5. PythonIDE connects back to the CLI, syncs the App workspace to the desktop, opens VS Code, and refreshes the preview after each auto-save.

Useful Simulator options:

npx pythonide-cli start --simulator --xcode-project=Py编程IDE.xcodeproj --xcode-scheme=pythonide
npx pythonide-cli start --simulator --derived-data=/private/tmp/pythonide-sim-build
npx pythonide-cli start --simulator --simulator-host=127.0.0.1
npx pythonide-cli start --simulator --no-simulator-build --app-bundle="/path/to/Python IDE.app"

VS Code companion development

For the smoothest development flow, start the CLI with the VS Code companion:

npx pythonide-cli start --project-dir=/Users/mac/Desktop/PythonIDE-Sync --editor=vscode-extension

After the app syncs a project, the CLI opens a VS Code extension development host for the synced workspace.

You can also open the companion manually:

npx pythonide-cli vscode --workspace=/Users/mac/Desktop/PythonIDE-Sync

The extension reads .pythonide/server.json, .pythonide/state.json, .pythonide/diagnostics.json, and .pythonide/events.jsonl from the synced workspace. The CLI owns the network connection to the iPhone/iPad; the extension uses the CLI's local command endpoint for Run, Stop, and diagnostics requests.

VSIX packaging

For local packaging:

npm run vscode:package

The output is written to:

vscode-extension/dist/pythonide-vscode-0.1.4.vsix

Install it locally with:

code --install-extension vscode-extension/dist/pythonide-vscode-0.1.4.vsix