Recording commands

To start a CPU performance capture, one of the three main recording commands can be used:

• run
• attach
• record

attach

The attach command will attach to a currently running process, or, when supported by the platform, to multiple running processes. For console platforms, you will always attach to the currently running application without the need to specify a specific process. For desktop platforms, like Windows, processes can be specified by name or process ID. The specific attach parameters depend on the platform, which are specified as a subcommand.

Examples:

Display all options and flags for attaching on Windows:

SuperluminalCmd attach windows --help

Attach to a single process on Windows by specifying process name:

SuperluminalCmd attach windows --process-name MyApplication

Attach to a single process on Windows by specifying process ID:

SuperluminalCmd attach windows --process-id 2045

Attach to multiple processes on Windows:

SuperluminalCmd attach windows --process-name MyApplication1 --process-name MyApplication2 --process-id 2045

run

The run command will launch an application and start recording immediately. The specific record parameters depend on the platform, which are specified as a subcommand. The path to the application and its parameters are always specified at the end of the command-line. This is to ensure that any parameters that are passed to the application will not clash with the parameters that are specified for the command-line tool.

Examples:

Display all options and flags for running an application on Windows:

SuperluminalCmd run windows --help

Run a program on Windows:

SuperluminalCmd run windows "c:\My Folder\MyApplication.exe"

Run a program on Windows with a different working folder, and pass parameters to MyApplication:

SuperluminalCmd run windows --working-dir "c:\My Folder\Data" "c:\My Folder\MyApplication.exe" --myparam 3

record

The record command will record everything that is currently running. For console platforms, this means that it will record the currently running application. For desktop platforms, like Windows, this will perform a system-wide capture. Specific processes can be selected when opening the capture file in Superluminal, or when using the resolve command.

Examples:

Display all options and flags for performing a system-wide capture on Windows:

SuperluminalCmd record windows --help

Perform a system-wide capture on windows:

SuperluminalCmd record windows

When a recording is created, it will produce a capture file with raw data that is platform-specific. It needs to be transformed into data that can be used in Superluminal, which is the resolving step. During the resolving step, any symbols are processed as well. By default, the symbol settings that are configured in the Superluminal UI will be used if they exist. The symbol settings can also be configured from the command-line directly, or passed separately onto the resolve commands. For more information on symbol configuration, see Symbol configuration.

The output from the resolve step will be a Superluminal session that contains all symbols that could be resolved, which can be transferred to other machines for analysis.

It is not necessarily needed to perform the resolve step by the command-line tool, as the Superluminal UI also accepts the platform-specific files and will perform the resolving when needed. It can still be convenient to perform this step in the command-line tool in cases where symbols are only available locally, but the analysis of the capture needs to be performed on a different machine. Another reason might be to perform the work of the resolving step on a server, instead of having to do it locally.

Resolving can be performed as part of the attach or run commands, and it can be performed as a separate step with the resolve command.

Examples:

Display all options and flags for resolving an '.etl' file on Windows:

SuperluminalCmd resolve windows --help

Run a program on Windows, and resolve it after the capture completes:

SuperluminalCmd run windows --resolve "c:\My Folder\MyApplication.exe"

Attach to "MyApplication" on Windows, and resolve it after the capture completes, using C:\SymbolCache for symbol cache:

SuperluminalCmd attach windows --process-name MyApplication --resolve --symbol-cache-dir "c:\SymbolCache"

Resolve an '.etl' capture file on Windows as a separate step, using C:\SymbolCache for symbol cache:

SuperluminalCmd resolve windows --symbol-cache-dir "c:\SymbolCache" "c:\My Folder\MyCapture.etl"

When resolving capture files, or when using the AI interfaces, the configured symbol settings are used for symbol resolution. By default, the command-line tool will read the settings that are configured by the Superluminal UI. The settings can also be configured through the command-line interface directly using the config command. The settings that are configured will also be used by the Superluminal UI.

Examples:

Display all options and flags for configuring symbol settings:

SuperluminalCmd config --help

Set the symbol cache directory for all platforms:

SuperluminalCmd config --set-symbol-cache "C:\SymbolCache"

Add a symbol server to the Windows symbol settings:

SuperluminalCmd config windows add-symbol-server --url "https://MySymbolServer.com"

List all configured symbol locations for Windows:

SuperluminalCmd config windows list"

To avoid having to configure symbol settings for each individual platform, the platform symbol settings are grouped by platform family. For example, the symbol settings for all Windows based platforms are configured using SuperluminalCmd config windows.

For the resolve command, the symbol settings can also be passed directly to the resolve command. This will use these settings on top of the existing symbol settings, but the parameters passed to the resolve command will not persist.

By default, all capture commands run in blocking mode, meaning that the command won't return until the capture is stopped. For integration in scripts and batch files, it is often convenient to be able to start a capture, do some work, and then stop a capture. The async mode is used specifically for those scenarios.

By specifying the --async-session option and a session name, the capture command will exit immediately after the capture is started. The capture will keep running so that other operations can be performed while capturing. The stop command will then stop the async capture session, and the cancel command will cancel the async capture session.

Example:

; Start a recording session named 'sl_session' and output to trace.etl
SuperluminalCmd record windows --async-session sl_session --capture-path ./trace.etl

; Do work here, for instance: run a number of processes in sequence
c:\MyBuild\MyProcess1.exe
c:\MyBuild\MyProcess2.exe
c:\MyBuild\MyGame.exe

; Stop the async session with the corresponding session name
SuperluminalCmd stop --async-session sl_session

; Optional: resolve the resulting capture file
SuperluminalCmd resolve windows --symbol-cache c:\SymbolCache ./trace.etl
								

The command-line tool exposes interfaces for AI agents through a command-line interface and an mcp. It is designed to quickly traverse Superluminal's complex data structures regardless of the capture size, and to minimize token usage while doing so.

The CLI is accessible through the llm command, and the mcp is accessible through the mcp command. The LLM tools are designed for AI agents and future releases may output different data structures. There are no backwards compatibility guarantees between releases, so it is not recommended to create tooling that depends on the output of the llm or mcp commands.

The llm requires access to valid symbol settings for the various operations it will perform. By default, it will use the symbol settings that were configured by the UI. For additional configuration from the command-line directly, see Symbol configuration.

Licensing

The use of the llm and mcp commands require an activated license. Other commands, like the recording commands, do not. If there is already an activated license on the machine, it will be used automatically, otherwise it needs to be activated by using the license command, or through the Superluminal UI. A purchased seat can be activated, or a trial can be started.

Examples:

Display all options and flags for licensing:

SuperluminalCmd license --help

Activate a purchased seat. This will open up a browser window where a user can sign in and activate the license:

SuperluminalCmd license activate

Activate a trial:

SuperluminalCmd license activate --trial

Claude

To use Superluminal's AI support with Claude, the llm interface of SuperluminalCmd can be used directly, or the MCP can be installed. To install the MCP, run:

claude mcp add superluminal --scope user -- "C:\Program Files\Superluminal\Performance\SuperluminalCmd.exe" mcp

After adding the MCP, start Claude and run the /mcp command to verify the MCP was installed correctly.

Codex

To use SuperluminalCmd in Codex, the llm interface can be used directly, or the mcp can be installed. When the llm interface is used by Codex, a daemon is launched that will be running in the background. Any subsequent llm commands will be sent to the daemon. As Codex launches each command in a separate shell, it can terminate the daemon when it terminates the shell after the command has executed. This causes subsequent commands to fail when the daemon is terminated. Therefore, the AGENTS.md file instructs Codex to keep the daemon alive, but to do so, it will need to run outside the sandbox and it will request the user for permission to do so.

The mcp does not require running outside the sandbox as it doesn't need to run a separate daemon. To avoid running outside the sandbox, it is recommended to instead use the mcp for Codex. The mcp can be installed by simply calling codex.cmd, for example:

codex.cmd mcp add superluminal -- "C:\Program Files\Superluminal\Performance\SuperluminalCmd.exe" mcp

Other agents

For information on how to install the mcp with other agents, refer to the documentation of your AI agent.

Feedback

We're eager to hear how well your agent of choice works with the llm interfaces that we offer, and how well they can manage to extract performance information for different performance scenarios. Contact us here.

The command-line tool is designed to be easily deployed to other machines without requiring a Superluminal license. This is convenient for recording on build machines or machines from people in the organization who want to make performance captures but don't perform any of the profiling work. An example is a QA department that makes performance captures, while the programming team can inspect the performance captures using the Superluminal UI.

The command-line tool is part of the Superluminal install itself. For easy deployment to remote machines, the make-redist command can be used, creating a tiny package that can be copied to other machines without the need to run an installer.

Examples:

Create a zip file of the currently installed SuperluminalCmd version:

SuperluminalCmd make-redist --output-zip ./SuperluminalCmd.zip

Output the files of the currently installed SuperluminalCmd version in directory ./SuperluminalCmd:

SuperluminalCmd make-redist --output-dir "./SuperluminalCmd"

By default, the deployment package will only contain the platforms that can be publicly distributed and will not include any console platforms. If you are a registered console developer and have any console platforms installed, the --include-consoles option will be available. This option will include platforms like PlayStation® and Xbox, so that capturing for these platforms is also enabled. However, the resulting package may only be distributed internally within the company.

SuperluminalCmd make-redist --output-zip ./SuperluminalCmd.zip --include-consoles