Reference

MCP server tools

The Qt Creator MCP server exposes the following tools to MCP clients. Each entry lists the tool's parameters, with the required ones marked.

ToolDescription
app_quit Quits Qt Creator.
build_add_config Creates a new build configuration for the active project's kit and, unless set_active is false, makes it active. build_type is matched against the build types the kit offers (such as "Debug", "Release", RelWithDebInfo, MinSizeRel). On a mismatch the error lists the available types. Useful to run or build in a configuration the project does not have yet.
  • build_type (string, required) - Build type to add, such as "Release" (matched case-insensitively against the kit's available build types).
  • set_active (boolean) - Make the new configuration active. Defaults to true.
build_cancel Stops the running build, as the Cancel Build button does. Defaults to the most recent build, which fails with reason:not_running if it has already ended.
  • build_id (integer) - Build to stop. Defaults to the most recent one.
build_get_compile_output Returns the raw Compile Output text of a build - the head and the tail of it, since the first error is the cause and a link or deploy failure has nothing before it. Prefer build_get_issues for the structured diagnostics. Reach for this when a build or deployment failed without producing any. Defaults to the most recent build. scope:"session" returns the pane's whole text instead, across builds and deployments alike.
  • build_id (integer) - Build to report on. Defaults to the most recent one.
  • max_chars (integer) - How much text to return (default 16384, clamped to 1000-204928). A marker naming the dropped character count stands in for what was left out.
  • scope (string) - "build" (default): one build's output. "session": everything the pane has shown since Qt Creator started, which ignores build_id.
build_get_current_config Gets the currently active build configuration.
build_get_issues Errors and warnings of a build, one compiler-style line each ("src/foo.cpp:42: error: ..."), relative to base_dir where they lie under it. Reports on the most recent build unless build_id says otherwise, and by default returns the errors, or the warnings when the build produced no errors - so one call covers a build either way. Pass details:true for the compiler's own echo of each issue, and scope:"current" for everything in the Issues pane rather than one build's own - a build system's parse errors, for instance, which no build produced.
  • build_id (integer) - Build to report on. Defaults to the most recent one.
  • details (boolean) - Append each issue's detail lines - the offending source and the notes under it, which build_get_compile_output carries as well. Off by default. Turn it on for a diagnostic whose summary alone does not say enough.
  • file (string) - Absolute path of a single file to report on.
  • max (integer) - How many lines to return (default 50, clamped to 1-1000). The first error is usually the cause and the rest cascade.
  • offset (integer) - How many matching issues to skip, for reading past a truncated reply.
  • scope (string) - "build" (default): what the build named by build_id produced. "current": everything the Issues pane holds now, which ignores build_id.
  • severity (string) - Which issues to return. "auto" (default) is the errors, or the warnings when there are no errors. error_count and warning_count are reported whichever you pick, and the reply says which severity it settled on.
build_get_status Reports a build's state, waiting for it to finish first: a running build blocks this call for up to wait_ms, a finished one answers at once. Defaults to the most recent build, whether build_project or the user started it. state:"running" means the wait budget ran out, not that anything went wrong - call again to keep waiting, and repeat until state is something else. Never sleep between calls. The waiting happens here. Counts only. Read the diagnostics with build_get_issues and the raw text with build_get_compile_output.
  • build_id (integer) - Build to report on. Defaults to the most recent one.
  • wait_ms (integer) - How long to wait for a running build before answering state:"running" (default 45000). Clamped to 0-55000: a longer wait outlives the request timeout of typical clients, which drops the session and cancels the build. Pass 0 for an immediate snapshot.
build_list_configs Lists available build configurations.
build_project Starts a build of the named project - the startup project when no name is given - and returns at once with a build_id. The build runs in the background. This call never waits for it. Wait for the verdict with build_get_status, then read the diagnostics with build_get_issues and the raw text with build_get_compile_output. None of them are carried here, so a build that succeeds costs one small reply. One build runs at a time. When one is already going this starts nothing and answers reason:build_in_progress with that build's build_id: wait on that ID, then call again.
  • project_name (string) - Project to build. Pass project_path as well when several loaded projects share the name.
  • project_path (string) - Absolute path to the project file (CMakeLists.txt, .pro, ...). Identifies the project when display names collide.
build_switch_config Switches to a specific build configuration.
  • name (string, required) - Name of the build configuration to switch to.
cmake_reconfigure Re-runs CMake on a project (equivalent to Build > Run CMake) and blocks until CMake finishes. Returns a verdict: {succeeded, error_count, warning_count, duration_ms, issues, summary_text}. Use after editing CMakeLists.txt to add a target or test so the next build_project/test_run sees the refreshed target list. The natural pattern is cmake_reconfigure -> build_project -> test_run. Uses the startup project if project is omitted.
  • mode (string) - normal (default): standard reconfigure. profiling: reconfigure with profiling enabled and open the CTF Visualizer with the resulting profile.
  • project (string) - Name of the project to reconfigure. Uses the startup project if omitted. Run project_list to see available names.
cmake_reset_configuration Discards the CMake configuration of the project's active build configuration (equivalent to Build > Clear CMake Configuration) and, unless reconfigure is false, configures it again from scratch, blocking until CMake finishes. Deletes CMakeCache.txt, CMakeFiles and the file-api reply directory in that build directory, so cache values set outside the configuration's initial CMake arguments are lost. Use this when a build directory is stale or broken - after a failed first configure, a plain cmake_reconfigure keeps re-running CMake without the initial arguments and cannot recover on its own. Switch configurations with build_switch_config to reset another one. Returns the same verdict as cmake_reconfigure.
  • project (string) - Name of the project to reset. Uses the startup project if omitted. Run project_list to see available names.
  • reconfigure (boolean) - Run CMake again after clearing the configuration. Defaults to true. Pass false to leave the project unconfigured.
cpp_find_callees Finds the functions called by the C++ function at a position - the outgoing call hierarchy - using the C++ code model. Give the file and a 1-based line and column pointing at a function name. Returns each called function grouped with its call sites (file, 1-based line and column, and source line text). It resolves the function's definition, so the body must be available. The file must belong to an open project.
  • column (integer, required) - 1-based column of the function name to resolve.
  • file (string, required) - Absolute path to the C++ file containing the function.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • line (integer, required) - 1-based line of the function name to resolve.
cpp_find_callers Finds the callers of the C++ function at a position - the incoming call hierarchy - using the C++ code model. Give the file and a 1-based line and column pointing at a function name. Returns each call site with its file, 1-based line and column, the source line text, and the enclosing function (with its own location) that makes the call. The file must belong to an open project.
  • column (integer, required) - 1-based column of the function name to resolve.
  • file (string, required) - Absolute path to the C++ file containing the function.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • line (integer, required) - 1-based line of the function name to resolve.
cpp_find_overrides Finds the overriding implementations of the virtual C++ member function at a position - go to implementation(s) - across the class hierarchy, plus the base declaration(s) it overrides. Give the file and a 1-based line and column on a function name. Returns "overrides" (each with its fully qualified name, signature and location), base_declarations, and whether the function is virtual. The file must belong to an open project.
  • column (integer, required) - 1-based column of the function name.
  • file (string, required) - Absolute path to the C++ file containing the function.
  • line (integer, required) - 1-based line of the function name.
cpp_find_references Finds all references (usages) of the C++ symbol at a position, using the C++ code model. Give the file and a 1-based line and column pointing at an identifier. Returns each usage with its file, 1-based line and column, the source line text, the containing function, and whether it is a read, write or declaration. The file must belong to an open project.
  • column (integer, required) - 1-based column of the identifier to resolve.
  • file (string, required) - Absolute path to the C++ file containing the symbol.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • line (integer, required) - 1-based line of the identifier to resolve.
cpp_find_signal_connections Finds the signal/slot connections involving the C++ function at a position, by scanning the connect() and disconnect() calls the code model can see. Give the file and a 1-based line and column on a signal, slot or other member function. Ask with a signal to learn which slots it is connected to, with a slot to learn which signals trigger it. Each connection reports its location, whether it is a connect or disconnect, the "role" the function plays in it (signal or slot), the sender, signal, receiver and slot arguments as written, how the slot is given (slot_kind: qt4_macro for SIGNAL()/SLOT(), member_pointer for &Class::member, lambda, or another expression), an optional connection_type, and the position of the "counterpart" argument, ready for cpp_get_symbol_info. Limits: only textual connect/disconnect calls in files the code model has parsed are seen - not connections made in .ui files, by connectSlotsByName, from QML, or through wrapper functions. A SIGNAL()/SLOT() macro the code model cannot resolve is matched by name alone and reported with "resolved" false.
  • column (integer, required) - 1-based column of the function name.
  • file (string, required) - Absolute path to the C++ file containing the function.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • line (integer, required) - 1-based line of the function name.
cpp_find_symbols Searches the project-wide C++ code model index by name - a fast "go to symbol". The index holds classes, enums, function definitions, signals and type aliases. It does not contain plain declarations (data members, globals, or member functions that are only declared), so an empty result does not prove a name is unused - use cpp_get_file_symbols for the complete symbol list of a known file. Give a case-insensitive name substring. Optionally restrict by "kind" and cap the count with "limit". Results are ranked (exact, then prefix, then substring) so the most relevant survive the cap. total_matches and "truncated" report when the cap dropped matches. Each match has its name, kind, fully qualified scope, type/signature, and file with 1-based line and column.
  • kind (string) - Optional: restrict to one kind. "function" is function definitions. "declaration" is type aliases and signals (the index holds no plain declarations).
  • limit (integer) - Optional: maximum number of results (default 200).
  • query (string, required) - Case-insensitive substring to match against symbol names (matched against the fully qualified name).
cpp_get_file_problems Returns the C++ code model diagnostics (parser and semantic warnings and errors) for a file, each with its severity and 1-based line and column. The file must be known to the code model, that is, a C++ source or header that belongs to an open project.
  • file (string, required) - Absolute path to the C++ source or header file.
cpp_get_file_symbols Returns the C++ symbols (classes, functions, enums, declarations) in a file from Qt Creator's C++ code model, each with its kind, fully qualified scope, type/signature and 1-based line and column. The file must be known to the code model, that is, a C++ source or header that belongs to an open project.
  • file (string, required) - Absolute path to the C++ source or header file.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
cpp_get_include_hierarchy Returns the include hierarchy of a C++ file from the code model: the files it includes directly (each with the 1-based line of the #include, the name as written, and whether it was a <global> or a "local" include), the files that include it directly (each with the line of their #include), and the #includes that could not be resolved to a file. Set "transitive" to also get the flattened closures: every file it pulls in, and every file that depends on it. The file must be known to the code model, that is, a C++ source or header that belongs to an open project or is included by one.
  • file (string, required) - Absolute path to the C++ source or header file.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • transitive (boolean) - Also return transitive_includes and transitive_included_by. Default false.
cpp_get_quick_fixes Lists the C++ quick-fixes and refactoring actions the editor offers at a position - what "Alt+Enter" would show - each with its description. Give the file and a 1-based line and column. This only lists the available actions. It does not apply them. The file is opened in an editor if it is not already, and must belong to an open project and be parsed (the actions depend on the editor's semantic info being up to date).
  • column (integer, required) - 1-based column of the position.
  • file (string, required) - Absolute path to the C++ file.
  • line (integer, required) - 1-based line of the position.
cpp_get_symbol_info Resolves the C++ symbol at a position and returns its name, fully qualified name, kind and type, plus its declaration and (for functions) definition locations - that is, go-to-definition. Give the file and a 1-based line and column pointing at an identifier. The file must belong to an open project.
  • column (integer, required) - 1-based column of the identifier.
  • file (string, required) - Absolute path to the C++ file.
  • line (integer, required) - 1-based line of the identifier.
cpp_get_type_hierarchy Returns the base and derived class hierarchy of the C++ class or struct at a position. Give the file and a 1-based line and column pointing at a class name. Returns the class with nested "bases" (up) and "derived" (down), each with name and location. The file must belong to an open project.
  • column (integer, required) - 1-based column of the class name.
  • file (string, required) - Absolute path to the C++ file.
  • line (integer, required) - 1-based line of the class name.
cpp_rename_symbol Renames the C++ symbol at a position across the whole project, using the code model - the rename refactoring. Give the file and a 1-based line and column on an identifier, and the new_name. By default this is a DRY RUN: it returns the edits it would make (each with file, 1-based line and column, length, and the old and new text) and changes nothing. Set "apply" to true to write the edits. Only files belonging to the open projects are edited, never Qt or system headers. skipped_edits and skipped_files report the usages left untouched by that filter, so a partial rename is visible rather than silent. Before anything is written the new name is checked for clashes: a declaration of that name in the same scope, a base-class member it would hide or start to override, an outer declaration it would shadow, or a declaration that would capture one of the renamed usages and make it mean something else. "conflicts" lists them with a severity. "apply" is refused while a hard conflict exists unless "force" is true. other_declarations_with_name lists unrelated indexed symbols that already have the new name, for information.
  • apply (boolean) - Write the edits to disk. Default false (dry run).
  • column (integer, required) - 1-based column of the identifier to rename.
  • file (string, required) - Absolute path to the C++ file containing the symbol.
  • force (boolean) - Apply even though the new name has a hard conflict. Default false.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • line (integer, required) - 1-based line of the identifier to rename.
  • new_name (string, required) - The new identifier name.
debugger_add_breakpoint Adds a new breakpoint in Qt Creator's debugger.
  • address (integer) - Memory address (for address or watchAddress type).
  • condition (string) - Optional condition expression.
  • enabled (boolean) - Whether the breakpoint is enabled. Defaults to true.
  • file (string) - Absolute path to the source file (for fileAndLine type).
  • function (string) - Function name (for function type).
  • ignore_count (integer) - Number of hits to ignore before breaking.
  • line (integer) - Line number in the source file (for fileAndLine type).
  • one_shot (boolean) - If true, the breakpoint is removed after the first hit.
  • type (string) - Breakpoint type. Defaults to fileAndLine.
debugger_add_watch_expression Adds an expression to the watch list in the current debug session. The expression is evaluated and its value updated as execution progresses. Returns the iname of the new watch entry (such as "watch.0"), which can be used with debugger_get_variable, debugger_set_variable, and debugger_remove_watch_expression. Returns an error if no debug session is active or the debugger is not paused.
  • expression (string, required) - Expression to watch (such as myVar, "ptr->field").
  • name (string) - Optional display name. Defaults to the expression.
debugger_collapse_all_children Recursively clears the expanded state of every descendant of the given variable, so re-expanding it shows its whole subtree collapsed at all levels. Returns an error if no debug session is active or the debugger is not paused.
  • iname (string, required) - Internal name of the variable (such as "local.myVar").
debugger_continue Resumes program execution in the debugger until the next breakpoint. Requires an active debug session that is paused.
debugger_delete_breakpoint Deletes a breakpoint by its ID (as returned by debugger_get_breakpoints or debugger_add_breakpoint).
  • id (integer, required) - ID of the breakpoint to delete.
debugger_evaluate_expression Evaluates an expression in the context of the current debug session. Returns the expression's value and type. Requires an active debug session that is paused.
  • expression (string, required) - Expression to evaluate (such as myVar, "ptr->field", "a + b").
debugger_get_breakpoints Returns all breakpoints currently set in Qt Creator's debugger.
debugger_get_call_stack Returns the call stack (stack frames) of the current debug session. Returns an error if no debug session is active or the debugger is not paused.
debugger_get_expanded_inames Returns the sorted set of inames currently marked as expanded in the Locals and Expressions view. Returns an error if no debug session is active or the debugger is not paused.
debugger_get_status Returns the current status of the debugger including whether a session is active, its state (paused/running/stopped), and the current position if paused.
  • include_log (boolean) - Also return the raw debugger log (the commands exchanged with the backend, such as GDB/MI) in a "log" field. Default false.
debugger_get_threads Returns all threads of the current debug session. Returns an error if no debug session is active or the debugger is not paused.
debugger_get_variable Returns the details of a single variable by its iname, including its children if it has any (such as struct members or array elements). If a child also has has_children=true, call debugger_get_variable again with that child's iname to retrieve its sub-fields. Returns an error if no debug session is active or the debugger is not paused.
  • iname (string, required) - Internal name of the variable (such as "local.myVar").
debugger_get_variables Returns local variables for the current stack frame. Optionally includes watch expressions. Variables with has_children=true may include a children array if already expanded. Otherwise call debugger_get_variable with the variable's iname to retrieve sub-fields. Returns an error if no debug session is active or the debugger is not paused.
  • include_watchers (boolean) - Also return watch expressions (default: false).
debugger_interrupt Pauses the currently running debuggee. Requires an active debug session that is running.
debugger_print_console_message Appends a message of the given type to the QML Debugger Console, exactly as the debugger would. Useful for exercising the console's auto-popup behavior. Does not require an active debug session.
  • text (string) - Message text.
  • type (string, required) - Message type: error, warning, debug, or default.
debugger_remove_watch_expression Removes a watch expression from the current debug session by its iname. Returns an error if the iname is not found or is not a watch expression, or if no debug session is active or the debugger is not paused.
  • iname (string, required) - Internal name of the watch entry to remove (such as "watch.0").
debugger_run_to_line Resumes execution until it reaches the given 1-based line in the given file, then stops (like the debugger's "Run to Line"). Requires an active debug session that is paused and an engine that supports running to a line.
  • file (string, required) - Absolute path of the source file.
  • line (integer, required) - 1-based line to run to.
debugger_select_frame Switches the current stack frame in the active debug session. Subsequent debugger_get_variables / debugger_evaluate_expression calls operate on the selected frame. Returns an error if no debug session is active or the debugger is not paused.
debugger_select_thread Switches the current thread in the active debug session. Returns an error if no debug session is active or the debugger is not paused.
debugger_set_display_format Sets the display format of a single variable (by iname) in the current debug session, as the Locals view context menu does. Use 0 to reset to Automatic. Common format codes: 0=Automatic, 5=Latin1String, 7=Utf8String, 12=Array of 10, 22=Decimal, 23=Hexadecimal, 24=Binary, 25=Octal. The format is remembered for the variable's current type only. Returns an error if no debug session is active or the debugger is not paused.
  • format (integer, required) - Display format code (0 = Automatic).
  • iname (string, required) - Internal name of the variable (such as "local.myVar").
debugger_set_variable Changes the value of a variable in the current debug session. Only works for variables where value_editable is true. Returns an error if no debug session is active or the debugger is not paused.
  • iname (string, required) - Internal name of the variable (such as "local.myVar").
  • value (string, required) - New value to assign.
debugger_start Starts a debug session and returns once the launch has been requested. Poll debugger_get_status for the session state. With no arguments, debugs the current startup project using its active run configuration and kit (does not build first - use the build_project tool beforehand if it may be out of date). If "executable" is given, debugs that executable directly (no project or build needed) with an optional kit, arguments, working directory and QML debugging. If remote_channel is also given, attaches to an already-running gdbserver or stub at that channel (for example, a bare-metal target) instead of launching the executable locally. The executable then only supplies symbols.
  • arguments (array) - Command-line arguments for the executable.
  • break_at_main (boolean) - Set a temporary breakpoint at main and stop there. Without "executable" it applies to the next debug start, which a pending build may delay. When attaching to a remote server it is honored by GDB and CDB kits only.
  • executable (string) - Absolute path to an executable to debug directly. If omitted, the startup project is used.
  • extended_remote (boolean) - Use "target extended-remote" for remote_channel (a "gdbserver –multi" server): the program is launched with run, so "arguments" are passed to it, instead of continuing an already-started process.
  • kit (string) - Kit ID to use (defaults to the default kit). Only used with "executable".
  • native_mixed (boolean) - Debug C++ and QML in one native combined session instead of starting a separate QML engine. Needs qml_debugging as well. The QTC_DEBUGGER_NATIVE_MIXED environment variable overrides this.
  • qml_debugging (boolean) - Enable QML debugging. Cannot be combined with remote_channel.
  • remote_channel (string) - Attach to an already-running gdbserver/stub at this channel (such as "localhost:1234" or "tcp:localhost:1234", CDB kits need the cdb form, such as "tcp:server=localhost,port=1234") instead of launching the executable. Requires "executable" for symbols.
  • working_directory (string) - Working directory (defaults to the executable's directory).
debugger_step_in Steps into the next function call in the debugger. Requires an active debug session that is paused.
debugger_step_out Steps out of the current function in the debugger. Requires an active debug session that is paused.
debugger_step_over Steps over the current line in the debugger. Requires an active debug session that is paused.
debugger_stop Stops the current debug session. Returns a message indicating whether the stop was successful.
device_add Creates a new device of the given device-type ID (such as GenericLinuxOsType) and adds it to the DeviceManager, without going through the GUI wizard. params sets the SSH parameters (host, port, userName, privateKeyFile, useKeyFile, timeout, hostKeyCheckingMode). Returns the new device ID.
  • displayName (string) - Display name for the new device (optional).
  • params (object) - SSH parameters: host, port, userName, privateKeyFile, useKeyFile, timeout, hostKeyCheckingMode (none|strict|allowNoMatch).
  • type (string, required) - Device-type ID, such as GenericLinuxOsType. See the type field of device_list, or use device_list_types.
device_detect_tools Connects to the device and runs the same auto-detection as the device configuration's "Run Auto-Detection Now" button: detects toolchains and debuggers on the device, detects on-device build tools (rsync, cmake, ...), and then creates kits for the device. Use this to set up a remote build/run/debug environment without the GUI. Returns the kits now associated with the device.
  • id (string, required) - Device ID.
device_list Lists all devices known to Qt Creator (ProjectExplorer::DeviceManager), with their ID, type, display name, connection state, and SSH parameters.
device_list_types Lists the device-type IDs that can be passed to device_add, with their display names and whether they can be created programmatically.
device_remove Removes the device with the given ID from the DeviceManager. As in the Devices preferences page, an auto-detected device can only be removed while it is disconnected. The local desktop device can never be removed. Kits referring to the device are left behind, so remove those with kit_remove.
  • id (string, required) - Device ID.
device_set_parameters Updates the display name and/or SSH parameters of an existing device. Only the fields present in params are changed. Others keep their current values.
  • displayName (string) - New display name (optional).
  • id (string, required) - Device ID.
  • params (object) - SSH parameters to change: host, port, userName, privateKeyFile, useKeyFile, timeout, hostKeyCheckingMode.
device_test Runs the device's connection tester (IDevice::createDeviceTester()), collecting the streamed progress and error messages, and returns the final result. Blocks until the test finishes or the timeout elapses.
  • id (string, required) - Device ID.
  • timeoutSeconds (integer) - Abort the test after this many seconds (default 60).
editor_close Closes a file in Qt Creator.
  • path (string, required) - Absolute path of the file to close.
editor_create_file Creates a new file at the specified path and optionally populates it with text. Creates parent directories automatically. Fails if the file already exists.
  • path (string, required) - Absolute path where the file should be created.
  • text (string) - Optional content to write into the new file.
editor_get_completions Returns the code-completion proposals at a position in a file, as the editor would offer them, from the engine that editor uses there - the language server when one serves the file, otherwise the editor's own model - so it works for any kind of file that completes in the editor: C++, QML, CMake, Python and so on. Useful before writing code. Give the file and a 1-based line and column (the cursor point, for example, just after a . or "::"). Returns the candidate completions, each with its text and any detail (signature/type), filtered and ranked by the prefix already typed. The file is opened in an editor if it is not already. An engine still loading the file proposes what it knows so far, as it would to a user.
  • column (integer, required) - 1-based column of the cursor position.
  • file (string, required) - Absolute path to the file.
  • limit (integer) - Maximum number of completions to return (default 200, at most 1000).
  • line (integer, required) - 1-based line of the cursor position.
editor_get_cursor_position Returns where the text cursor sits in the editor the user is working in: the "path" of that editor, the 1-based "line" and "column", and the line_text of the line it is on, cut to 400 characters with line_text_truncated set when the line is longer. When the cursor has a selection, has_selection is true and it spans selection_start_line/selection_start_column to selection_end_line/selection_end_column, which editor_select_text turns back into the selected text. cursor_count is above 1 when the editor holds several cursors, in which case the position reported is the main one. This is how to resolve a request phrased as "the current line" or "the method the cursor is in": the coordinates are the 1-based line and column that editor_open, editor_select_text and the cpp_* and lsp_* tools take, so cpp_get_symbol_info resolves the symbol under the cursor and cpp_get_file_symbols the one it sits inside. This is the text cursor: the mouse pointer is ui_get_pointer_position, and editor_move_cursor moves that pointer rather than the caret. Read-only.
editor_get_folds Returns the code-folding structure of the current text editor, one entry per line: the 1-based "line", the fold_indent (nesting level behind the fold markers - a line starts a foldable region when the next line has a greater indent, and the region extends until the indent drops back), whether the line is currently "folded", whether it is ifdefed_out (inactive/greyed preprocessor code), and a trimmed "text" snippet. Use it to check which lines are foldable, how far each fold region reaches, and how folding interacts with inactive code. Read-only.
editor_get_text Returns the text of the current text editor as the user sees it, including unsaved changes. Optionally restrict to a line range via start_line/end_line (1-based, inclusive). Also works for editors without a file path, such as diff views or other temporary editors, which fs_read_text cannot read; "path" is empty for those and display_name names the editor. Unlike editor_select_text this leaves the cursor and selection alone. Read-only.
  • end_line (integer) - Last line to return, 1-based inclusive (optional).
  • start_line (integer) - First line to return, 1-based inclusive (optional).
editor_list_open Lists currently open files.
editor_list_visible Lists all files that are currently visible to the user in an editor.
editor_move_cursor Warps the real mouse pointer to a root coordinate with QCursor::setPos, so a screen recording shows the cursor. By default it glides over a few steps. Pass steps=1 to jump. This only moves the pointer - it does not click.
  • steps (integer) - Interpolation steps for the glide (default 20).
  • x (integer, required)
  • y (integer, required)
editor_open Opens a file in Qt Creator, optionally jumping to a specific line and column.
  • column (integer) - 1-based column number to jump to (optional, requires line).
  • line (integer) - 1-based line number to jump to (optional).
  • path (string, required) - Absolute path of the file to open.
editor_reformat Reformats a specified file using Qt Creator's code formatting rules. Opens the file if not already open.
  • path (string, required) - Absolute path to the file to reformat.
editor_save Saves a file in Qt Creator.
  • path (string, required) - Absolute path of the file to save.
editor_select_text Selects text in the current text editor, from start_line/start_column to end_line/end_column (1-based, the columns default to the start of the first and the end of the last line). Sets up the selection that behavior like printing a selection, commenting or an external tool replacing the selection depends on - typing cannot produce it, and the incremental find highlights matches without moving the cursor. Returns the selected text.
  • end_column (integer) - 1-based column, defaults to the end of the line.
  • end_line (integer, required) - 1-based line the selection ends on.
  • start_column (integer) - 1-based column, defaults to 1.
  • start_line (integer, required) - 1-based line the selection starts on.
fakevim_send_keys Funnels a string of keystrokes into the FakeVim handler of the current editor, exactly as if typed in Vim. The string uses Vim key notation: printable characters stand for themselves and special keys are angle-bracket escapes, so "ihello<Esc>" inserts "hello" and returns to normal mode, "3j" moves down three lines, "dd" deletes a line and "<C-v>" is Ctrl-V. FakeVim must be enabled (Edit > Preferences > FakeVim, or the Use FakeVim action). Returns the 1-based cursor line and column after the keys were processed, so a scenario can assert the effect of a motion or edit.
  • keys (string, required) - Keystrokes in Vim notation, such as "ihello<Esc>" or "3j".
fs_apply_patch Applies a unified diff to files on disk using the configured patch command. Give the diff in "patch". "strip" is the number of leading path components to drop from each file in the diff (like patch -p): use 1 for git-style diffs with a/ and b/ prefixes (the default), 0 for diffs with plain paths. Paths are resolved against working_directory, which defaults to the startup project's directory. Set "revert" to true to undo the diff instead. On failure nothing is left half-applied only if the patch command rejects atomically. Check "output" for the tool's own messages (including rejected hunks).
  • patch (string, required) - The unified diff to apply.
  • revert (boolean) - Revert the diff instead of applying it.
  • strip (integer) - Leading path components to strip (patch -p). Default 1.
  • working_directory (string) - Directory the diff paths are relative to. Defaults to the startup project's directory.
fs_get_info Returns metadata for a path using Utils::FilePath: existence, type, size, modification time, executable bit and permissions. Local and remote paths are both supported through Qt Creator URL-like paths such as ssh://user@host/path or docker://id/path. Remote access is transparent.
  • path (string, required) - Path to inspect (local or remote URL-like path).
fs_list_directory Lists directory entries using Utils::FilePath, with name, path, type, size, modification time and executable bit. Optionally filter by glob name patterns and recurse. Local and remote directories are both supported through Qt Creator URL-like paths such as ssh://user@host/path or docker://id/path. Remote access is transparent.
  • name_filters (array) - Glob patterns to match, such as ['*.txt'] (optional).
  • path (string, required) - Path of the directory (local or remote URL-like path).
  • recursive (boolean) - Recurse into subdirectories (optional).
fs_make_directory Creates a directory and any missing parents with Utils::FilePath::ensureWritableDir(). Local and remote paths are both supported through Qt Creator URL-like paths such as ssh://user@host/path or docker://id/path.
  • path (string, required) - Path of the directory to create (local or remote URL-like path).
fs_read_bytes Reads raw file contents and returns them base64-encoded - use this for binary files. For text use fs_read_text. Optionally restrict to a byte range with offset/length. Local and remote files are both supported through Qt Creator URL-like paths such as ssh://user@host/path or docker://id/path. Remote access is transparent. reason distinguishes an empty directory from one that could not be read: device_unavailable, not_found, not_a_directory.
  • length (integer) - Maximum number of bytes to read (optional).
  • offset (integer) - Byte offset to start reading from (optional).
  • path (string, required) - Path of the file (local or remote URL-like path).
fs_read_text Returns the content of the file as plain text. Optionally restrict to a line range with start_line/end_line (1-based, inclusive). For binary content use fs_read_bytes instead. Local and remote files are both supported through Qt Creator URL-like paths such as ssh://user@host/path or docker://id/path. Remote access is transparent.
  • end_line (integer) - Last line to return, 1-based inclusive (optional).
  • path (string, required) - Path of the file. May be a local path or a remote URL-like path (ssh://user@host/path, docker://id/path).
  • start_line (integer) - First line to return, 1-based inclusive (optional).
fs_remove Removes a file, or a directory when recursive is true, with Utils::FilePath::removeFile() / removeRecursively(). Local and remote paths are both supported through Qt Creator URL-like paths such as ssh://user@host/path or docker://id/path.
  • path (string, required) - Path to remove (local or remote URL-like path).
  • recursive (boolean) - Remove directories and their contents (optional).
fs_replace_in_directory Replaces all matches of a text pattern recursively in all files within a directory with replacement text.
  • case_sensitive (boolean) - Whether the search should be case sensitive.
  • directory (string, required) - Absolute path of the directory to search in.
  • pattern (string, required) - Text pattern to search for.
  • regex (boolean) - Whether the pattern is a regular expression.
  • replacement (string, required) - Replacement text.
fs_replace_in_file Replaces all matches of a text pattern in a single file with replacement text.
  • case_sensitive (boolean) - Whether the search should be case sensitive.
  • path (string, required) - Absolute path of the file to modify.
  • pattern (string, required) - Text pattern to search for.
  • regex (boolean) - Whether the pattern is a regular expression.
  • replacement (string, required) - Replacement text.
fs_replace_in_projects Replaces all matches of a text pattern in files matching a file pattern within a project (or all projects) with replacement text.
  • case_sensitive (boolean) - Whether the search should be case sensitive.
  • file_pattern (string, required) - File pattern to filter which files to modify (such as '*.cpp', '*.h').
  • pattern (string, required) - Text pattern to search for.
  • project_name (string) - Optional: name of the project to search in (searches all projects if not specified).
  • regex (boolean) - Whether the pattern is a regular expression.
  • replacement (string, required) - Replacement text.
fs_write_bytes Writes base64-decoded raw bytes to a file, creating or overwriting it - use this for binary files. For text use fs_write_text. This writes directly to disk and does not route through the editor. Local and remote files are both supported through Qt Creator URL-like paths such as ssh://user@host/path or docker://id/path.
  • base64 (string, required) - Raw bytes to write, base64-encoded.
  • path (string, required) - Path of the file (local or remote URL-like path).
fs_write_text Overwrites the file's text content with the provided string. Behavior depends on whether the file is currently open in a Qt Creator editor: - Not open: writes directly to disk. - Open with an unchanged buffer: updates the editor's in-memory buffer (visible to the user immediately). The change is not persisted to disk until editor_save is called. - Open with unsaved changes: refused with reason file_open_with_unsaved_changes to avoid silently overwriting the user's edits. Caller should ask the user to save (or call editor_save) and retry. For binary content use fs_write_bytes instead. Also supports files on remote devices with URIs like docker://... or ssh:// and others.
  • path (string, required) - Absolute path of the file.
  • plain_text (string, required) - Text to write into the file.
get_application_output Returns recent log output captured from Qt Creator's qDebug()/qCInfo()/qCWarning()/... stream, including Q_LOGGING_CATEGORY output, as well as messages written to the General Messages pane (under the general category). Read incrementally by passing the cursor returned by the previous call as sinceCursor. Optionally filter by a logging-category prefix, such as qtc.remotewindows or general.
  • category (string) - Only return lines whose logging category starts with this prefix (optional).
  • maxLines (integer) - Maximum number of lines to return (most recent within the range). Defaults to 200.
  • sinceCursor (integer) - Return only lines newer than this cursor. Use the cursor from a previous response. Omit or 0 to read from the start of the buffer.
get_help_contents Returns the top-level nodes of the Help Contents tree (as shown in the Help mode sidebar), built for the active filter. Reports duplicate_titles - titles that appear on more than one top-level node, which happens when several versions of a component are registered without a narrowing filter. "truncated" says nodes were left out because max_nodes ran out, timed_out that the wait for the tree to be built was given up on.
  • max_depth (integer) - Tree depth to return (default 1, top level only, at most 10).
  • max_nodes (integer) - Maximum number of nodes to return (default 2000, at most 20000).
get_registered_documentation Returns the namespaces of all documentation registered in the Help system. Several registered Qt versions produce several namespaces that differ only by their version suffix (for example "org.qt-project.qtcore.680").
git_blame Returns line-by-line authorship (git blame) for a file: for each line, the commit hash, author and commit subject. Give the "file" and optionally a start_line/end_line range (1-based) to limit the output. start_line alone blames from there to the end, end_line alone from the beginning. An end_line past the end of the file makes git fail, so omit it to blame to the end. At most "limit" lines are returned. total_lines and "truncated" report what was left out.
  • end_line (integer) - Optional: last 1-based line to blame.
  • file (string, required) - Absolute path to the file to blame.
  • limit (integer) - Maximum number of lines to return (default 2000).
  • start_line (integer) - Optional: first 1-based line to blame.
git_diff Returns the unified diff of uncommitted changes in the repository that contains a path. Give any file or directory inside the repository as "path". Set "staged" to diff the index against HEAD, or restrict the diff to one "file". The diff is cut at the last full line that fits into "limit" characters. total_characters and "truncated" report what was left out.
  • file (string) - Optional: restrict the diff to this file.
  • limit (integer) - Maximum number of characters of diff to return (default 100000).
  • path (string, required) - Absolute path to a file or directory inside the repository.
  • staged (boolean) - Diff staged changes (index vs HEAD) instead of the working tree (default false).
git_log Returns recent Git commits for the repository that contains a path, most recent first, each with its hash, author, date and subject. Give any file or directory inside the repository as "path". Optionally cap the count with max_count and restrict history to one "file".
  • file (string) - Optional: restrict the log to this file's history.
  • max_count (integer) - Maximum number of commits (default 20).
  • path (string, required) - Absolute path to a file or directory inside the repository.
git_status Returns the Git working-tree status of the repository that contains a path: the current branch and the list of changed files, each with its two-character porcelain status code. Renames and copies also report the original_path. On a detached HEAD "branch" is empty and "detached" is true. Give any file or directory inside the repository as "path".
  • path (string, required) - Absolute path to a file or directory inside the repository.
kit_add_to_project Adds a build target for each of the given kits to a project. Kits may be identified by kit ID or display name (see kit_list). Defaults to the active startup project when neither project_name nor project_path is given. Returns a per-kit results array with status added/already_present/not_found/failed. The call does not abort on the first error. When multiple loaded projects share the same display name, pass project_path to disambiguate.
  • kits (array, required) - Kit IDs or display names to add to the project.
  • project_name (string) - Display name of the project. Optional. Defaults to the active startup project.
  • project_path (string) - Absolute path to the project file. Unambiguously identifies the project and takes precedence over project_name.
kit_get_aspect_options Lists the values a kit aspect can be set to (for item-backed aspects such as the debugger, toolchain, Qt version or device). Each option has a value (to pass to kit_set_value) and a display name. An empty list means the aspect is free-form.
  • aspect_id (string, required) - Aspect ID (from kit_get_aspects).
  • kit_id (string, required)
kit_get_aspects Lists the configurable aspects of a kit (debugger, toolchains, Qt version, device, ...). Each entry has the aspect ID, its display name, a human-readable current value, and the raw stored value. Use the aspect ID with kit_get_aspect_options and kit_set_value.
  • kit_id (string, required) - Kit ID (as reported by kit_list).
kit_list Lists all kits configured in Qt Creator. Each entry includes the kit name, its ID, whether it is valid, whether it has warnings, whether it is the default kit, whether it was auto-detected (and SDK-provided), a filesystem-friendly name, the kit's run and build device, and an issues array with validation messages for invalid or warning kits.
kit_list_for_project Lists the kits a project is configured for (one per build target). Defaults to the active startup project when neither project_name nor project_path is given. Each kit entry has the same fields as kit_list plus is_active, which marks the kit of the project's active target. When multiple loaded projects share the same display name, pass project_path to disambiguate (returns reason:ambiguous_name with candidates otherwise).
  • project_name (string) - Display name of the project. Optional. Defaults to the active startup project.
  • project_path (string) - Absolute path to the project file. Unambiguously identifies the project and takes precedence over project_name.
kit_remove Removes kits from Qt Creator, identified by kit ID or display name (see kit_list). Use it to clean up after device_detect_tools, which creates a kit per toolchain found on a device. kit_list reports each kit's run and build device, so the kits belonging to a device can be picked out. Returns a per-kit results array with status removed/not_found/sdk_provided/ambiguous_name. The call does not abort on the first error. SDK-provided kits cannot be removed. Removing a kit drops the corresponding build target from every project using it, so its build and run settings are lost.
  • kits (array, required) - Kit IDs or display names to remove.
kit_rename Gives a kit another display name, as editing it on the Kits preferences page does. Worth knowing why it matters: the default build directory of a project is derived from the kit name, so two kits that share one name also share one build directory and overwrite each other's configuration. Kits generated per Qt version collide that way when the versions carry the same version number and ABI. The kit may be given by ID or display name (see kit_list). A name several kits share has to be told apart by ID, which is the case this is for.
  • kit (string, required) - Kit ID or current display name.
  • name (string, required) - The new display name.
kit_set_active Makes the project build and run with one of the kits it is configured for, as choosing it in the kit selector does. The kit may be given by ID or display name (see kit_list, and kit_list_for_project for which are configured and which is active). A display name that several kits share is refused, so use the ID to tell them apart. Defaults to the active startup project when neither project_name nor project_path is given.
  • kit (string, required) - Kit ID or display name to make active.
  • project_name (string) - Display name of the project. Optional. Defaults to the active startup project.
  • project_path (string) - Absolute path to the project file. Unambiguously identifies the project and takes precedence over project_name.
kit_set_value Sets a kit aspect to a value. Pass the value reported by kit_get_aspect_options for item-backed aspects (the exact stored type is preserved). Free-form aspects take the value as-is. Aspects holding a list, such as the CMake configuration, take an array of strings.
  • aspect_id (string, required)
  • kit_id (string, required)
  • value (required) - Value to set.
list_help_filters Returns the documentation filters known to the Help system, the available component versions, and the currently active filter. Selecting a filter narrows the Contents tree to matching documentation.
lsp_call_hierarchy Returns the callers ("incoming") or the callees ("outgoing") of the function at a position, as the language server (clangd for C++, or whatever server is configured for the file type) computes them from its index. Give the file and a 1-based line and column on a function name. Each entry has the function's name, kind, file and position, the from_ranges where the calls happen, and, with a "depth" above 1, its own "calls" nested below it. clangd supports outgoing calls from version 20.1 on and reports an error before that. The file is opened in a hidden editor if it is not open. A server that is still starting asks to be retried.
  • column (integer, required) - 1-based column of the function name.
  • depth (integer) - How many levels to follow, 1 to 3 (default 1).
  • direction (string) - "incoming" for the callers (default), "outgoing" for the callees.
  • file (string, required) - Absolute path to the source file.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • line (integer, required) - 1-based line of the function name.
lsp_definition Returns where the symbol at a position is defined, as the language server (clangd for C++, qmlls for QML, or whatever server is configured for the file type) resolves it - templates, overloads and macros included. Give the file and a 1-based line and column on an identifier. "kind" chooses the question: "definition" (default) for the symbol's own definition, or its declaration when the server knows no definition. type_definition for the definition of the symbol's type, for a variable or parameter. "implementation" for the overrides of a virtual function or the classes implementing an interface. Each location has its file and 1-based line/column to end_line/end_column. The file is opened in a hidden editor if it is not open. A server that is still starting asks to be retried.
  • column (integer, required) - 1-based column of the identifier.
  • file (string, required) - Absolute path to the source file.
  • kind (string) - What to go to (default "definition").
  • line (integer, required) - 1-based line of the identifier.
lsp_hover Returns what the language server shows on hover at a position: the declaration, its type, and its documentation comment, as markdown or plain text, plus the range the information applies to. Answers come from clangd for C++, qmlls for QML, or whatever server is configured for the file type, so this is the tool for a symbol's documentation. Give the file and a 1-based line and column on an identifier. The file is opened in a hidden editor if it is not open. A server must be configured for its file type, and a server that is still starting asks to be retried.
  • column (integer, required) - 1-based column of the identifier.
  • file (string, required) - Absolute path to the source file.
  • line (integer, required) - 1-based line of the identifier.
lsp_references Finds every reference to the symbol at a position, as the language server (clangd for C++, qmlls for QML, or whatever server is configured for the file type) knows them from its index - templates, overloads and macros included, across all files it has indexed. Give the file and a 1-based line and column on an identifier. Each reference has its file and 1-based line/column to end_line/end_column. The declaration is included unless include_declaration is false. The list is sorted by file and position and capped by "limit", with "total" and "truncated" saying what was left out. The file is opened in a hidden editor if it is not open. A server that is still starting asks to be retried.
  • column (integer, required) - 1-based column of the identifier.
  • file (string, required) - Absolute path to the source file.
  • include_declaration (boolean) - Also list the symbol's declaration(s). Default true.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • line (integer, required) - 1-based line of the identifier.
lsp_rename Renames the symbol at a position everywhere the language server (clangd for C++, qmlls for QML, or whatever server is configured for the file type) knows it - templates, overloads and macros included. Give the file, a 1-based line and column on the identifier, and the new_name. By default this is a dry run: it returns the edits the server proposes (each with file, 1-based position, old and new text) and changes nothing. Set "apply" to true to make the edits: they reach the files on disk, and a file open in an editor is updated there too, unless it had unsaved changes of its own, in which case it is edited but not saved and named in unsaved_files. The server refuses a name that clashes within the same scope. Other symbols that already carry the new name anywhere in the project are listed as "conflicts" for you to judge, and do not block. The file is opened in a hidden editor if it is not open. A server that is still starting asks to be retried.
  • apply (boolean) - Make the edits. Default false (dry run).
  • column (integer, required) - 1-based column of the identifier to rename.
  • file (string, required) - Absolute path to the source file.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • line (integer, required) - 1-based line of the identifier to rename.
  • new_name (string, required) - The new identifier name.
lsp_symbols Searches the language server's index for symbols by name - the way to turn a name into the file and position the other lsp_ tools take. Give a "query" (matched fuzzily, ranked by the server) and any "file" the server handles, which picks the server: a C++ file for clangd, a QML file for qmlls. Each symbol has its name, kind, container (class or namespace), file and 1-based line/column of its name. "limit" caps the count. "truncated" says whether more matched. The file is opened in a hidden editor if it is not open. A server that is still starting asks to be retried.
  • file (string, required) - Absolute path to a file the server handles. Chooses the server.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • query (string, required) - The symbol name to search for.
lsp_type_hierarchy Returns the base classes ("supertypes"), the derived classes ("subtypes") or both of the class at a position, as the language server (clangd for C++, or whatever server is configured for the file type) computes them from its index. Give the file and a 1-based line and column on a class name. Each entry has the type's name, kind, file and position, and, with a "depth" above 1, its own "supertypes" or "subtypes" nested below it. The file is opened in a hidden editor if it is not open. A server that is still starting asks to be retried.
  • column (integer, required) - 1-based column of the class name.
  • depth (integer) - How many levels to follow, 1 to 3 (default 1).
  • direction (string) - "supertypes" for the bases, "subtypes" for the derived classes, "both" (default) for both.
  • file (string, required) - Absolute path to the source file.
  • limit (integer) - Maximum number of results (default 200, capped at 1000).
  • line (integer, required) - 1-based line of the class name.
plugin_list Lists all installed plugins together with their current run state and whether they can be loaded at runtime without a restart.
plugin_load Soft-loads a plugin, and its soft-loadable dependencies, into the running Qt Creator without a restart. Only works for plugins marked as soft-loadable. There is no matching unload.
  • name (string, required) - Name of the plugin to load, as reported by plugin_list.
plugin_save_settings Writes the current enabled/disabled state of all plugins to disk so it survives a restart. Use after plugin_load to make a runtime-loaded plugin load again on the next start.
process_run Executes the command and returns the exit code as well as standard output and error.
  • arguments (string) - Arguments passed to the command.
  • command (string, required) - Command to execute.
  • working_dir (string) - Directory in which the command is executed.
profiler_perf_get_status Returns whether the perf profiler is recording, whether a perf run is active, and a summary of the data collected so far: the sample/event count and the trace duration in nanoseconds.
profiler_perf_start Starts the CPU (perf) profiler on the current startup project (perf profiler run mode), using its active run configuration and kit. Does not build first - use the build_project tool beforehand if it may be out of date. Recording starts automatically. Poll profiler_perf_get_status, and use profiler_perf_stop (or let the application exit) to finalize the trace. Returns as soon as the run is requested, unlike run_project with run_mode PerfProfiler.RunMode, which waits for the run to finish and gives no access to the trace.
profiler_perf_stop Stops the running perf profiler session by requesting its run control to stop, which finalizes the trace. Returns an error if no perf session is running. Poll profiler_perf_get_status afterwards for the finalized sample count.
profiler_qml_get_status Returns the QML profiler state (Idle/AppRunning/AppStopRequested/AppDying, or Unavailable if the profiler is gone), whether the server is recording, whether a profiler run is active, and a summary of the data collected so far: the event count and the trace duration in nanoseconds.
profiler_qml_start Starts the QML profiler on the current startup project (QML profiler run mode), using its active run configuration and kit. Does not build first - use the build_project tool beforehand if it may be out of date. Recording starts automatically. Poll profiler_qml_get_status for progress, and use profiler_qml_stop (or let the application exit) to finalize the trace. Returns as soon as the run is requested, unlike run_project, which waits for the run to finish.
profiler_qml_stop Stops the running QML profiler session by requesting its run control to stop, which finalizes the trace. Returns an error if no profiler session is running. Poll profiler_qml_get_status afterwards for the finalized event count.
project_find_files Finds all files matching the pattern in a given project.
  • pattern (string, required) - Pattern for finding the file, either a glob pattern or a regex.
  • project_name (string) - Name of the project to limit the search to (optional).
  • regex (boolean) - Whether the pattern is a regex (default is false).
project_get_current Gets the currently active project.
project_get_dependencies Lists project dependencies for all projects.
  • name (string, required) - Name of the project to query dependencies for.
project_get_modules Describes a project's structure: its runnable application targets (name, build key, executable, and defining project file) and the other loaded projects it depends on (from the session Dependencies settings). Selects the project by project_name or project_path, defaulting to the startup project. "targets" comes from the build system's application targets, so it lists executables and runnable utility targets only - libraries and other non-runnable targets are not reported - and it is empty until the project is configured with a kit and parsed.
  • project_name (string) - Name of the project. Defaults to the startup project.
  • project_path (string) - Project file path, to disambiguate a shared name.
project_list Lists all loaded projects. Each entry includes the project name, its file path, the active version control branch, and whether it is the current startup project (is_active). Use path or branch to disambiguate when multiple projects share the same display name (common in multi-worktree setups).
project_list_repositories Lists all known version control repositories (such as Git and Subversion) that are within the directories of all open projects.
  • name (string, required) - Name of the project to query repositories for.
project_open Opens a project in Qt Creator from a project file path (such as CMakeLists.txt, a .pro, .qbs, or .qmlproject file). If the project is already open, returns success with already_open=true. The opened project is added to the session. Use project_set_active to make it the startup project.
  • path (string, required) - Absolute path to the project file to open (such as CMakeLists.txt, .pro, .qbs, .qmlproject).
project_set_active Changes the active startup project (the one Qt Creator builds, runs, and debugs by default). Accepts project_name, project_path, or both. When multiple loaded projects share the same display name (for example, the same project open in two Git worktrees), you must also supply project_path to disambiguate. The tool returns reason:ambiguous_name with a candidates array if project_path is omitted and the name matches more than one project.
  • project_name (string) - Display name of the project to activate. Required unless project_path alone is sufficient to identify it.
  • project_path (string) - Absolute path to the project file. Unambiguously identifies the project and takes precedence over project_name when multiple projects share the same display name.
project_show_panel Switches to Projects mode and shows one of the active project's settings panels. Pass panel = "build", "deploy" or "run" for the target's Build/Deploy/Run Settings tabs, or a project-panel ID (such as "Editor") for the left-hand project settings. Use this to reach settings only shown in these panels, such as the run configuration's "Executable on device" field. Returns an error when no project is open.
  • panel (string, required) - "build", "deploy" or "run" for the target settings tabs, or a project-panel ID for the left-hand project settings.
qt_add_version Registers the Qt version a qmake belongs to, as "Add..." on the Qt Versions preferences page does. Returns what the version turned out to be, so that a caller can tell which platform it was recognized as. A qmake that is already registered is returned as it stands.
  • name (string) - Display name for the version. Defaults to the name the detection came up with.
  • qmake_path (string, required) - Path to the qmake executable of the Qt to add.
qt_get_directory Returns the Qt installation paths for the Qt version used by the active kit of the current project. Includes the installation prefix, version string, bin, header, and library paths.
  • project_name (string) - Name of the project to query. Defaults to the active startup project.
register_documentation Registers the given .qch documentation files with the Help system and waits for the registration to finish. Returns the resulting namespaces. Registering several versions of the same component is how duplicate top-level nodes appear in the Contents tree. timed_out tells a caller that the wait was given up on, so the namespaces are whatever was registered at that point rather than the finished result.
  • paths (array, required) - Absolute paths to .qch documentation files.
run_configure Selects an existing run configuration (by display name or type ID, see run_list_configs) as the active one and/or sets its executable, the arguments the application is started with, and its working directory. Setting the executable only works for run configurations that have one, such as the bare-metal "Custom Executable" configuration. Then debugger_start (with no arguments) debugs it with its run configuration's own launch path. Several run configurations share one type ID, so an ID matching more than one fails with reason "ambiguous" and the matching display names in "candidates", rather than picking one of them.
  • arguments (string) - Command-line arguments to start the application with, as one string. An empty one clears them.
  • executable (string) - Executable to set on the run configuration (local path).
  • id (string, required) - Run configuration display name, or type ID when it is unique.
  • set_active (boolean) - Make this the active run configuration.
  • working_directory (string) - Directory to start the application in. An empty one restores the run configuration's default.
run_list_configs Returns the project's existing run configurations. Each entry includes the display name, the run configuration type ID, whether it is the active one, and the resolved runnable: executable, arguments, working directory, and the full run environment (key-value map, as the application would see it).
run_list_modes Lists every run mode that has a registered run worker, and whether the current startup project can be run in each one right now (with the reason if not). Use a runnable ID as run_project's run_mode. Interactive modes have dedicated tools (debugger_start, profiler_qml_start).
run_project Runs the current startup project and waits for it to finish. Progress messages from the application are streamed during execution. On success, returns the full output plus the run outcome: exitCode (absent if the process crashed or the terminal launch failed) and succeeded (exit code 0). On build failure, returns isError=true with structured content in the same shape as the Issues pane's tasks (issues array + summary). By default this is a normal run. Pass run_mode to run the project under a different, non-interactive run mode such as an analyzer (the run must finish on its own). Interactive modes have dedicated tools: use debugger_start for debugging and profiler_qml_start for the QML profiler. Returns an error if there is no startup project, no active build configuration, or the project cannot currently be run in the requested mode.
  • run_mode (string) - Run-mode ID to run the startup project under. Defaults to the normal run mode (RunConfiguration.NormalRunMode). Examples: PerfProfiler.RunMode, RunConfiguration.QmlProfilerRunMode. The mode must have a run worker registered for the project's device and run to completion. Interactive modes belong to debugger_start / profiler_qml_start.
search_directory Searches for a text pattern recursively in all files within a directory and returns all matches.
  • case_sensitive (boolean) - Whether the search should be case sensitive.
  • directory (string, required) - Absolute path of the directory to search in.
  • pattern (string, required) - Text pattern to search for.
  • regex (boolean) - Whether the pattern is a regular expression.
search_file Searches for a text pattern in a single file and returns all matches with line, column, and matched text.
  • case_sensitive (boolean) - Whether the search should be case sensitive.
  • path (string, required) - Absolute path of the file to search.
  • pattern (string, required) - Text pattern to search for.
  • regex (boolean) - Whether the pattern is a regular expression.
search_projects Searches for a text pattern in files matching a file pattern within a project (or all projects) and returns all matches.
  • case_sensitive (boolean) - Whether the search should be case sensitive.
  • file_pattern (string, required) - File pattern to filter which files to search (such as '*.cpp', '*.h').
  • max_results (number) - How many matches to return (default 200). Clamped to 1-5000. total_matches reports how many there were.
  • pattern (string, required) - Text pattern to search for.
  • project_name (string) - Optional: name of the project to search in (searches all projects if not specified).
  • regex (boolean) - Whether the pattern is a regular expression.
session_get_current Gets the currently active session.
session_list Lists available sessions.
session_load Loads a specific session.
  • session_name (string, required) - Name of the session to load.
session_save Saves the current session.
set_help_filter Sets the active documentation filter by name. Pass an empty name to clear the filter (show all documentation).
  • filter (string) - Filter name, or empty for no filter.
set_help_version_filter Creates (if needed) and activates a documentation filter that shows only the given component version, for example "6.12.0". Pass an empty version to clear the filter. Use this to collapse duplicate top-level nodes that come from several registered versions. The filter this tool created is removed again when the filter is cleared or another version replaces it, so the user's Help configuration is left as it was.
  • version (string) - Version like "6.12.0", or empty to clear.
set_logging_rules Applies QLoggingCategory filter rules at runtime, equivalent to QT_LOGGING_RULES, such as qtc.remotewindows.*=true. Separate multiple rules with newlines. Use this to enable a logging category before reading it back with get_application_output.
  • rules (string, required) - Logging rules, one per line, such as qtc.*.debug=true.
settings_get Returns the individual settings (aspects) of a preference page: key, label, current value and default value. Use the page ID from settings_list_pages. Read-only.
settings_list_pages Lists Qt Creator preference pages whose settings are exposed as aspects, so they can be read with settings_get and changed with settings_set. Pages with hand-rolled widgets (no aspect container) are omitted. Read-only.
settings_set Sets a single aspect-based setting to a new value and persists it. The change takes effect immediately (the aspect emits its change signal), so this is the programmatic equivalent of toggling the setting in the Preferences dialog. Identify the setting by its key (settingsKey from settings_get). The value is coerced to the setting's current type.
  • key (string, required) - settingsKey of the setting (see settings_get).
  • page (string, required) - Settings page ID.
  • value (required) - New value (bool/number/string), coerced to the setting's type.
settings_show_page Opens Preferences on the given page, so that its widgets can be driven with ui_find_widgets, ui_click_widget and the item tools. Pages build their widgets lazily, so a page that has never been shown has none to find. Give the page id from settings_list_pages, or none to open Preferences where it last was.
  • page_id (string) - Page ID, such as "Alien.Settings" (optional).
setup_android Runs Android auto-configuration - the same action as applying the Android SDK preferences page - which registers the NDK toolchains and (re)creates the automatic Android kits from the configured SDK/NDK and the installed Qt-for-Android versions. Use after the Android SDK location and a Qt-for-Android version are configured to obtain a usable Android kit without driving the preferences GUI. Returns all kits present afterwards, each with the ID of its run device type, so that the Android ones can be told apart, plus the Android Qt versions and Android toolchains that the kit creation had to work with. Fails if the configured Android SDK is not usable, which is otherwise indistinguishable from having no NDK and no Qt-for-Android version.
test_get_details Returns per-test details for the named tests from the most recent run. By default returns only the small, actionable fields - status, failure (the extracted assertion for a failing test), warnings (any warning lines), file/line, duration - so a build/test/fix loop never has to wade through a huge log. Names typically come from test_run / test_get_last_results (`failures` / `tests_with_warnings`). Unmatched names appear in `not_found`. Pass include:["log"] for the full (tail-capped) output as `message`, and include:["messages"] for the qDebug/qInfo/... context array. `truncated` is set when any text was capped. The full log is always in Qt Creator's Test Results pane.
  • include (array) - Optional heavy fields beyond the default status/failure/warnings: "log" adds the full (capped) output as message. "messages" adds the context array. Omit to keep the response small.
  • names (array, required) - Test names to fetch details for.
test_get_last_results Returns a read-only summary of the most recent test run. Reflects whatever was last executed - by test_run or by the user clicking Run/Debug in the Tests pane. Returns counts plus name lists for failures and tests-with-warnings. Use test_get_details with specific test names to see per-test messages, file/line, and full debug log. Calling test_run instead would re-execute and potentially erase a flaky or debug-only failure.
test_get_status Reports whether a test run is currently in progress and whether the snapshot holds results worth looking at. Call this before test_run if there is any chance the user has just produced an interesting result (for example, a debug-mode failure) in the Tests pane that you do not want to overwrite.
test_list Enumerates every test class Autotest currently knows about, with its functions. Useful as a discovery step before calling test_run - gives exact class and function names to pass as test_run({scope: "named", names: [Class::function]}) without guessing from build artifacts. Each entry carries the framework label (such as "Qt Test", "Google Test"). Returns empty if Autotest has not finished parsing yet or the project has no recognized tests.
test_run Builds (if needed) and runs autotests, then returns a compact summary: counts, list of failed/fatal/skipped test names, and list of passing test names that emitted warnings. Runs the whole suite unless you pass scope=named with names - prefer that when you already know which tests you care about. A full run can be slow enough to hit a client timeout. Equivalent to clicking Run (or Debug, with mode=debug) in the Tests pane. Returns once the run finishes. To see per-test details (messages, file/line, and so on), follow up with test_get_details using any test name from the run - failures, warnings, or just a passing test you want to inspect. test_get_details returns the full message log for every named test regardless of its outcome. An empty messages[] means the test did not emit anything. Note: each call replaces the current snapshot - if the user has just run something interesting in the UI, call test_get_last_results first instead of clobbering it. Read `finished` first. When it is true the summary is this run's result. When it is false nothing failed - the run has not ended yet, and the response carries a run_id, elapsed_ms and a reason of still_running, or joined_existing_run if the run it is waiting for is one that was already going. Call test_run again with that run_id to keep waiting, and repeat until finished is true. Do not start a second run and do not sleep between calls: each call does the waiting for you. A run already going - whether this tool started it or the user hit Run in the Tests pane - is joined rather than refused, so a repeated call cannot launch a competing run.
  • mode (string) - How to execute. run is the normal mode. debug runs them under the debugger, which can reproduce timing-sensitive failures that do not manifest in plain Run mode (for example, qFatals that only fire when stepped through). Debug mode is much slower. Use it for narrowing in on a known failure.
  • names (array) - Test names to run. Requires scope=named. Passing names with any other scope is an error. Use Class, or Class::function for frameworks that list functions - CTest entries have none, so only the whole test runs. Names typically come from `failures` or `tests_with_warnings` in a previous summary, or from test_list. Names must already be present in Autotest's current model - if a name is not found, call cmake_reconfigure first to trigger a re-parse (needed after adding or renaming test functions).
  • run_id (integer) - Attach to the run with this ID instead of starting one. Use the run_id from a previous still_running response.
  • scope (string) - Which tests to run. all runs every discovered test (default). selected means whatever the user has ticked in the Tests pane, not a selection the caller passes, so it is rarely what a caller wants. failed re-runs the tests that failed in the previous run. named runs only the tests in the `names` array. Set this to run one test, as `names` with any other scope is rejected.
  • wait_ms (integer) - How long to block before returning reason:still_running, in milliseconds (default 45000). Clamped to 1000-55000: a longer wait outlives the request timeout of typical clients, which drops the session and cancels the run. Poll with run_id instead of asking for a longer wait.
ui_activate_menu_item Finds a menu bar entry or an item in a currently-open menu by visible text and activates it through the menu API. Shows a submenu (QMenu::popup) so a scenario can navigate into it, and triggers a leaf item. The trigger is posted asynchronously, so this does not block even when it opens a modal dialog. Pair with ui_find_menu_item and editor_move_cursor to drive a menu with the cursor.
  • title (string, required) - Visible text of the menu or item.
ui_activate_mode Switches Qt Creator to a top-level mode (the left mode bar) and returns the current mode ID. Omit "mode" to just query. A mode only activates when it is available (for example, "Project" needs an open project). Common IDs: "Welcome", "Edit", "Design", "Project" (the Projects/build-run-settings mode), "Mode.Debug", "Help".
  • mode (string) - Mode ID to activate (optional, omit to just query).
ui_answer_message_box Clicks a button on the currently-open message box - the active modal one, or the most recently shown box still visible - to dismiss it. The button is matched by its text with the mnemonic '&' and case ignored, or by the untranslated standard-button name, so "Yes", "No", "Ok", "Cancel" work whatever the UI language. See ui_get_message_boxes for the available buttons. Returns an error (with available_buttons) if there is no open box or no match.
  • button (string, required) - Text of the button to click (mnemonic '&' and case ignored).
ui_call_action Calls an action by its ID.
  • id (string) - ID of the action to call.
ui_click_item Clicks one item of the item view matching the widget query, by delivering a left click at its center, so the view reacts exactly as it would to the user - selection, activation and any command the item carries. Name the item by its full path ("Outgoing / Fix the thing") or, when unambiguous, by its label. Zero or multiple matches are an error.
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • context_menu (boolean) - Ask the row for its context menu instead of clicking it. The menu is then driven with ui_activate_menu_item.
  • double_click (boolean) - Double-click the row. Some views act only on that (opening what the row stands for), and a single click then does nothing.
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • item (string, required) - Full path or label of the item to click.
  • modifiers (string) - Keyboard modifiers held while clicking, "+"-separated out of "ctrl", "shift", "alt" and "meta". This is how a multi-selection is built: ctrl adds the row to the selection, shift extends it to the row.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
ui_click_tab Clicks one tab of the QTabBar matching the widget query, by the text on it. A tab is not a widget of its own, so it cannot be reached with ui_click_widget.
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • tab (string, required) - Text on the tab, matched after trimming and stripping '&'.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
ui_click_widget Clicks the single widget matching the query with a synthetic left press and release, the events a real click produces - a widget is free to act on the mouse itself, and some do. The click lands on the widget's center, except on a check box or radio button, where only the indicator reacts to one. The query must resolve to exactly one visible widget - zero or multiple matches are an error, so the tool never silently picks a widget. The result describes the widget as ui_find_widgets does, so a toggle can be told from a miss.
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
ui_find_actions Finds actions matching a query string.
  • query (string) - String to search for in action names.
ui_find_items Lists the items of the single item view matching the widget query - a tree, list or table - with the path of labels leading to each row, its text, whether it has children, is expanded, selected or enabled, and its geometry in root coordinates. This is the addressing layer for ui_click_item and ui_set_item_expanded, and the way to assert what a view actually shows. A view that fills lazily only has the children of rows that were expanded, so expand first and look again.
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • item (string) - Only report items whose full path or label is exactly this.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
ui_find_menu_item Returns the geometry, in root coordinates, of a menu bar entry (such as "Help") or of an item in a currently-open menu (such as "About Qt Creator"), matched by visible text ('&' and a trailing ... are ignored). Menu items are QActions, not addressable widgets, so this is how a scenario drives menus with the cursor. Read-only.
  • title (string, required) - Visible text of the menu or item.
ui_find_widgets Resolves a semantic widget query against the live Qt Creator UI by walking all widgets (including dialogs and popups). Returns every match with its class, objectName, visible text - an excerpt for a long one, with text_truncated set - enabled/visible state, checked state where the widget has one - with the three-way check_state for a tristate check box, whose "checked" is true for the partial state too - geometry in root coordinates and top-level window ID. This is the addressing layer for ui_click_widget / ui_type_text / ui_select_combo_item: use it to discover selectors and to check that a query is unambiguous before acting on it. Read-only.
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
ui_get_message_boxes Returns the QMessageBox popups (warnings, errors, questions, ...) shown since startup, including transient or non-modal ones that never reach the log or message panes. Each entry has the title, text, informative_text, icon, buttons, modality, and openness. Pass open_only=true to get only the currently-visible ones.
  • open_only (boolean) - Only return message boxes that are still open.
ui_get_pointer_position Returns the pointer position in screen coordinates, which is what a screen recording shows. Useful to check that a paced click actually moved it.
ui_list_windows Lists the top-level windows of the running Qt Creator - the main window and any open dialogs or popups - each with its class, objectName, title, geometry, window ID, and whether it is active or modal. Use it to see which dialog is up before addressing widgets inside it. Read-only.
  • include_invisible (boolean) - Also list hidden windows (default false).
ui_mouse_event Delivers one mouse press, move or release to the widget matching the query at widget-local coordinates (x, y). Because the three actions are separate calls, a caller can press, do something else, then move and release - for example, hold a drag on a QMainWindow dock separator across a relayout. describeWidget in the result gives the widget's screen geometry to compute coordinates from.
  • action (string, required) - Which mouse action to send.
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
  • x (integer, required) - Widget-local x.
  • y (integer, required) - Widget-local y.
ui_press_keys Sends a key chord parsed with QKeySequence (such as "Ctrl+K", "Escape", "Return", "Ctrl+Shift+P", "Down") to the focused widget, or to the single widget matching the query. Use it for keys a widget handles directly (Return, Escape, Tab, arrows) and to demonstrate a shortcut being pressed. To reliably trigger an action's effect regardless of focus, prefer ui_call_action - a synthetic key event does not always drive application-wide shortcuts.
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • keys (string, required) - Key sequence, such as "Ctrl+K" or "Escape".
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
ui_read_general_messages Returns the recent General Messages pane text - the warnings, errors and status that plugins surface to the user outside the Compile Output and Application Output panes. Use it to see diagnostics that are otherwise only shown in the GUI.
ui_read_output_pane Returns the plain text of an output pane (such as "Application Output", "General Messages", "Compile Output"), identified by its display name. This is the text the user sees in the pane, distinct from get_application_output which returns Qt Creator's own log stream. Call without a name (or with an unknown one) to get the list of available panes. Panes that are not plain-text (such as Issues) report pane_has_no_text_output. Read-only.
  • max_lines (integer) - Return only the last N lines (optional).
  • name (string) - Display name of the pane (see available_panes).
ui_screenshot Captures a window and returns it as a PNG. If widget query fields are given, the target's top-level window is captured (for example, window_title of a dialog). Otherwise the active window, falling back to the main window. Rendering is done in-process with QWidget::grab(), so the image is deterministic and never blank - no compositor or retry needed, unlike an external screen grab. Pass path to also save the PNG to disk. The base64 is embedded in the result only when no path is given (or embed=true).
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • embed (boolean) - Embed base64 PNG in the result (default: true unless a path is given).
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • path (string) - Optional file path to save the PNG to.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
ui_select_combo_item Selects an item by its text in the single QComboBox matching the query, as a user picking it would: the index is set and activated() is emitted, which many combo boxes act on rather than currentIndexChanged. This avoids the pitfall that pressing Return on a focused combo box opens its dropdown instead of choosing. The query must resolve to exactly one QComboBox.
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • item (string, required) - Exact text of the item to select.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
ui_set_demo_pace Slows the widget tools down so a screen capture of a driven session looks like someone using the IDE: the pointer travels to what ui_click_widget clicks at a set speed, buttons show as held down, and ui_type_text arrives character by character. All delays are in milliseconds. Zero everywhere (the default) restores the immediate behavior that tests want.
  • click_hold_ms (integer) - How long a click is held, for example, 120.
  • key_delay_ms (integer) - Pause after each typed character, for example, 60.
  • pointer_speed (integer) - How fast the pointer travels to a target, in pixels per second, for example, 700, so that the time it takes follows the distance. Zero leaves the pointer alone.
ui_set_item_expanded Expands or collapses one item of the QTreeView matching the widget query. Needed to reach nested items at all: a view that fills lazily asks its source for the children only when a row is expanded, so the children appear in ui_find_items a moment later, not immediately.
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • expanded (boolean) - Expand it (default), or collapse it when false.
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • item (string, required) - Full path or label of the item.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
ui_show_caption Puts a line of text over the main window for a while, and returns once it is gone. For a screen recording of a driven session: a step with no visible trigger, a mode being switched or a run being started from a tool, otherwise just happens. An empty text removes the caption right away.
  • seconds (number) - How long it stays, 2 by default.
  • text (string, required) - What the caption says.
ui_type_text Types text by delivering key events, so widgets that react to typing (line edits, text editors) update as if the user typed. If widget query fields are given they select and focus the target (which must resolve to exactly one widget). Otherwise the current focus widget receives the input. It types text: a special key has no notation here, so a "\n" in the input is a newline character rather than a Return press - use press_keys for a key sequence, or fakevim_send_keys for Vim notation such as ":w<CR>".
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • input (string, required) - The text to type. Typed as characters - see the tool description for how to send a key instead.
  • mode (string) - "append" (the default) types at the cursor and keeps what is already there. "set" replaces the content, so the widget ends up holding exactly the input - use it for a filter or a line edit that a previous call left non-empty. An empty input then clears it. Only text inputs accept it.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.
ui_widget_exists Reports whether the widget query matches any live widget, and how many. Use it as an assertion (for example, "the preview opened") without failing on zero matches the way ui_click_widget does. Read-only.
  • class_name (string) - Meta-object class name, such as QPushButton. Matches the exact class or any subclass (QAbstractButton matches QPushButton).
  • include_invisible (boolean) - Also match hidden widgets (default false).
  • index (integer) - Pick the nth match, 0-based and in on-screen order (top to bottom, then left to right), instead of failing when the query matches several widgets. Listing tools report just that match.
  • object_name (string) - Exact objectName(). The most robust selector: stable across translation and layout changes.
  • text (string) - Visible text (button/label/combo/groupbox), or, for an input like a line edit, its buddy label's text. Matched exactly after trimming and stripping '&' accelerators. Readable but translation-sensitive.
  • window_title (string) - Restrict to widgets whose top-level window title contains this (case-insensitive), for example, to disambiguate an OK button by its dialog.

See also Set up Qt Creator MCP server and How to: Use AI.

Reference

Copyright © The Qt Company Ltd. and other contributors. Documentation contributions included herein are the copyrights of their respective owners.
The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation.
Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.