Claudus CLI
claudus runs individual commands from a terminal or script. claudus mcp is the persistent stdio interface for MCP clients. Both use the same native backend connection and tool dispatch.
The examples use Windows PowerShell and the short executable name on PATH. On macOS/Linux, use claudus and your platform's absolute project paths.
Discover, describe, call
claudus.exe help
claudus.exe help call
claudus.exe toolsets --json --project-path "C:\Projects\MyProject\MyProject.uproject"
claudus.exe describe ClaudusBridgeEditor.ClaudusBridgeReflectionToolset --project-path "C:\Projects\MyProject\MyProject.uproject"
claudus.exe call ClaudusBridgeEditor.ClaudusBridgeOrchestrationToolset GetEditorBusyState '{}' --project-path "C:\Projects\MyProject\MyProject.uproject"
toolsets and describe inspect the live Unreal catalog. They are engine-backed even when the editor window is closed. --project-path enables hidden startup for these commands; --no-launch-headless prevents it.
For complex arguments, write UTF-8 JSON to a file and pass @file. This avoids shell quoting errors:
claudus.exe call ClaudusBridgeEditor.ClaudusBridgeReflectionToolset SetProperty '@set-property.json' --project-path "C:\Projects\MyProject\MyProject.uproject" --agent asset-assistant
The file must contain the fields returned by describe, for example objectPath, propertyPath, valueJson, bTransact and bNotify for SetProperty. valueJson is itself a JSON-encoded value. Inspect the object and schema before editing; reflection and package workflows covers this boundary.
Arguments may also be an inline JSON object or - to read stdin. tool <name> calls a top-level MCP tool; rpc <method> sends a raw JSON-RPC request. Use call for ordinary toolset operations.
Pick the runtime deliberately
| Option or command | Behavior |
|---|---|
--project-path <absolute .uproject> | Select the exact project; connecting tool commands may launch a hidden backend. |
--project-dir <absolute directory> | Discovery-only selection unless --launch-headless is explicit. |
--launch-headless | Allow starting the project's hidden Unreal commandlet when needed. |
--no-launch-headless | Require an existing backend. |
status --json | Read registry records without connecting. |
doctor --json | Check installation and launch prerequisites without connecting. |
ready --wait --timeout 300 --launch-headless | Connect and wait for catalog readiness; explicit launch is useful when starting closed. |
ping --json --timeout 10 | Probe a backend; does not launch it unless explicitly requested. |
Use the project selector on each command. For nonstandard engine installations, --unreal-editor-cmd <absolute executable> overrides discovery. UNREAL_EDITOR_CMD and UE_ENGINE_ROOT are also supported.
Results, progress and failure handling
One-shot commands write their result to stdout and diagnostics to stderr. --raw preserves the full JSON-RPC response. A tool's result may contain a returnValue string holding JSON; inspect both the outer result and the tool's own success fields.
--out <file>writes the result to a file.--progressrequests progress notifications on stderr.--timeout <seconds>bounds a one-shot request; its default is 900 seconds. Persistentmcphas a separate per-request timeout, default 0 (disabled).- Cancellation is cooperative. A timeout does not roll back engine changes or prove a synchronous operation stopped.
| One-shot exit code | Meaning |
|---|---|
0 | Request completed successfully. |
1 | Tool or RPC error. |
2 | Invalid command or arguments. |
3 | Backend unavailable or connection lost. |
4 | Refused by policy, ownership, lock or quota rules. |
7 | Timeout or cancellation. |
Other command families have their own help and exit contracts. Check both the exit code and returned data before continuing a script. After an uncertain mutation, inspect current state before issuing it again.
Offline work
help, version, status, doctor, policy show and timeline queries need no Unreal backend. The separate asset utility offers check, type, to-json, from-json, diff and raw; these operations have narrower package-format support than Unreal itself. See reflection and assets.
For coordinated editing, use a stable --agent, package locks, and timeline checkpoints.