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.

Read the project's skills

The project carries its own Agent Skills — reusable instructions stored as Unreal assets, so every agent that opens the project sees the same set. Read the relevant one before doing the work:

claudus.exe skill list --project-path "C:\Projects\MyProject\MyProject.uproject"
claudus.exe skill show /ClaudusBridge/Skills/ClaudusBridge_Niagara.ClaudusBridge_Niagara_C --project-path "C:\Projects\MyProject\MyProject.uproject"

skill list prints each skill's path and description; skill show prints the full instructions for the paths you name. Authoring is deliberately not a verb here: creating or updating a skill writes an asset, so it goes through an explicit claudus call ToolsetRegistry.AgentSkillToolset CreateSkill @args.json.

Stand the backend down for a rebuild

A compiler cannot overwrite a DLL that a running process has loaded, so the hidden backend has to exit before you rebuild the plugin or the project:

claudus.exe quiesce --project-path "C:\Projects\MyProject\MyProject.uproject"

quiesce asks the backend to finish in-flight work, release the project writer lock and exit, and it returns only once the binaries are actually writable — so the build can start on the next line. Any agent can issue it; a rebuild never waits on another client disconnecting. It is idempotent when nothing is running, never starts a backend, and refuses to close a visible editor, which may hold unsaved packages.

It is not a maintenance lock: another client can start a fresh backend while your build runs. Keep project requests paused until the rebuild finishes. Full details in Rebuilding the plugin.

Results, progress and failure handling

One-shot commands write their result to stdout and diagnostics to stderr, so a pipe carries only the result. --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.

Output shape follows one rule for every command: human-readable on a terminal, JSON when stdout is a pipe or a file. Ask for a shape explicitly with --format human|json, --json as the shorthand, or the CLAUDUS_FORMAT environment variable for a whole session. asset is the exception by design: it streams the converter's own output verbatim.

status and quiesce add a stable errorCode beside the human error — NO_INSTANCES, UNSUPPORTED_LEGACY_PLUGIN, EDITOR_OWNS_PROJECT, STAND_DOWN_FAILED, TEARDOWN_TIMEOUT, BACKEND_UNREACHABLE — and timeline reports {"error":{"code":"E_*"}}. Where a code is present, branch on the code and never on the message.

• --out <file> writes the result to a file.
• --progress requests progress notifications on stderr.
• --timeout <seconds> bounds a one-shot request; its default is 900 seconds. Persistent mcp has 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.