CLI reference

Use the built-in help for the authoritative command list:

ursa --help

For subcommand-specific help:

ursa mcp-server --help
ursa exec --help
ursa rag-ingest --help
ursa rag-query --help

Common top-level commands

ursa --config config.yaml
ursa --print-config
ursa --config config.yaml --name my-agent --group default
ursa --config config.yaml --use-web

Main subcommands

Current URSA installations include subcommands for:

• running the MCP server,
• managing groups,
• managing persistent agents,
• sharing/importing agents,
• managing persistent RAG collections,
• non-interactive execution.

Use ursa --help to confirm the exact set in your installed version.

Python callback API

ursa.cli.callbacks.HITLLogEventHandler

Bases: CallbackRenderingMixin, AsyncCallbackHandler

Render structured agent/tool progress events to the REPL console.

Source code in src/ursa/cli/callbacks.py

class HITLLogEventHandler(CallbackRenderingMixin, AsyncCallbackHandler):
    """Render structured agent/tool progress events to the REPL console."""

    def __init__(self, console: Console, workspace: Path):
        self.console = console
        self.workspace = Path(workspace).resolve()
        self._last_agent: str | None = None
        self._inflight_tools: dict[Any, dict[str, Any]] = {}
        self.emitted_any = False

    @property
    def ignore_llm(self) -> bool:
        return True

    async def on_chat_model_start(
        self,
        serialized: Any,
        messages: Any,
        *,
        run_id,
        parent_run_id=None,
        tags=None,
        metadata=None,
        **kwargs,
    ) -> None:
        return None

    async def on_llm_start(
        self,
        serialized: Any,
        prompts: Any,
        *,
        run_id,
        parent_run_id=None,
        tags=None,
        metadata=None,
        **kwargs,
    ) -> None:
        return None

    async def on_tool_start(
        self,
        serialized: dict[str, Any],
        input_str: str,
        *,
        run_id,
        parent_run_id=None,
        tags=None,
        metadata=None,
        inputs: dict[str, Any] | None = None,
        **kwargs,
    ) -> None:
        tool_name = self._tool_name(serialized)
        payload = self._tool_input_payload(inputs, input_str)
        self._inflight_tools[run_id] = {
            "name": tool_name,
            "input": payload,
        }
        if tool_name == "run_command":
            self._print_run_command_start(payload.get("query"))
        elif tool_name == "read_file":
            self._print_read_file_start(
                payload.get("path") or payload.get("filename")
            )
        elif tool_name in {"write_code", "write_code_with_repo"}:
            self._print_write_code_start(
                payload.get("filename"),
                payload.get("path"),
                payload.get("code"),
            )
        elif tool_name in {"edit_code", "edit_experience"}:
            self._print_edit_code_start(
                payload.get("filename"),
                payload.get("path"),
                payload.get("old_code"),
                payload.get("new_code"),
            )

    async def on_tool_end(
        self,
        output: Any,
        *,
        run_id,
        parent_run_id=None,
        tags=None,
        **kwargs,
    ) -> None:
        tool_info = self._inflight_tools.pop(run_id, {})
        tool_name = tool_info.get("name")
        payload = output.content if isinstance(output, ToolMessage) else output
        success = (
            output.status == "success"
            if isinstance(output, ToolMessage)
            else True
        )
        if tool_name == "run_command":
            self._print_run_command_end(
                payload,
                query=tool_info.get("input", {}).get("query"),
                success=success,
            )
        elif tool_name == "read_file":
            self._print_read_file_end(
                payload,
                path=tool_info.get("input", {}).get("path")
                or tool_info.get("input", {}).get("filename"),
            )
        elif tool_name in {"write_code", "write_code_with_repo"}:
            self._print_write_code_end(
                payload,
                filename=tool_info.get("input", {}).get("filename"),
                path=tool_info.get("input", {}).get("path"),
                success=success,
            )
        elif tool_name == "edit_code":
            tool_input = tool_info.get("input", {})
            self._print_edit_code_end(
                payload,
                filename=tool_input.get("filename"),
                path=tool_input.get("path"),
                success=success,
            )

    async def on_tool_error(
        self,
        error: BaseException,
        *,
        run_id,
        parent_run_id=None,
        tags=None,
        **kwargs,
    ) -> None:
        tool_info = self._inflight_tools.pop(run_id, {})
        tool_name = tool_info.get("name", "tool")
        if not self._is_file_tool(tool_name) and tool_name != "run_command":
            return
        self.console.print(f"[error]✖ {tool_name} failed.[/]")
        self.emitted_any = True
        for line in self._display_lines(error):
            self.console.print(f"[dim]  {line}[/]")

    async def on_custom_event(
        self,
        name: str,
        data: Any,
        *,
        run_id,
        tags=None,
        metadata=None,
        **kwargs,
    ) -> None:
        if name != DEFAULT_EVENT_NAME or not isinstance(data, dict):
            return
        # Tool events may also carry an ``agent`` field identifying their
        # owner. Treat the primary tool discriminator as more specific than
        # that ownership metadata so named-agent artifacts are still rendered.
        if "tool" in data:
            tool = self._clean(data.get("tool"))
            self._print_event_artifact(data)
            if tool == "run_command":
                return
            if not self._is_rendered_tool(tool):
                return
            if tool == "read_file" and self._has_inflight_tool("read_file"):
                return
            if tool == "write_code" and self._has_inflight_tool(
                "write_code",
                "write_code_with_repo",
            ):
                return
            if tool == "edit_code" and self._has_inflight_tool("edit_code"):
                return
            self._print_tool_event(data)
        elif "agent" in data:
            self._print_agent_event(data)