5. Commands

Commands are found throughout Sublime Text. Almost all actions are carried out by Commands. Commands are connected to:

Plus you can run commands directly by calling: view.run_command('<command_name>', {args}) (e.g. in the Console or from within a Plugin).

Commands are also used by many types of Sublime Text resource files. In essence, Commands are the bread-and-butter of getting things done within Sublime Text.

You can see (and execute) most of the publicly-accessible Commands via the Command Palette: Tools > Command Palette... (normally ctrl+shift+p).

You can also create your own commands using Plugins.

See also https://docs.sublimetext.io/reference/commands.html .

5.1. Adding Existing Commands to Command Palette

When a packages implement new Commands that should also be available in the Command Palette, they are added to it using a .sublime-commands file.

5.1.1. Variables Available in .sublime-commands Args

Some commands take paths as parameters. Among these, some commands (e.g. open_file) support variables passed in strings like ${packages}/path/to/file.ext. These commands appear to not be preprocessed, but instead are passed verbatim into the command and the command itself converts them. So what variables may be passed is up to the command.

Commands expect forward-slash directory separators in paths if not otherwise noted, including on Windows (for example, /C/Program Files/Sublime Text/sublime_plugin.py).

Often, relative paths in arguments to commands are assumed to start at the <data_path>.

A few commands

“${var_name}” <– from within a string, and $var_name <– outside of a string

Variables currently known:

$project:

path to project?

$packages:

path

$0:

specifies where cursor should go when inserting a snippet

$platform:

(Windows|Linux|OSX)

Examples:

Preferences > Settings uses the edit_settings command.

{
    "caption": "Preferences: Settings",
    "command": "edit_settings",
    "args":
    {
        "base_file": "${packages}/Default/Preferences.sublime-settings",
        "default": "// Settings in here override those in \"Default/Preferences.sublime-settings\",\n// and are overridden in turn by syntax-specific settings.\n{\n\t$0\n}\n"
    }
},

When command-logging via sublime.log_commands(True) is turned on in the Console, and Preferences: Settings is executed via the Command Palette, it results in the following logged in the Console before opening the read-only version from with Sublime Text’s core.(This was when the new Settings window had not already been opened previously.)

command: edit_settings {
    "base_file": "${packages}/Default/Preferences.sublime-settings",
    "default": "// Settings in here override those in \"Default/Preferences.sublime-settings\",\n// and are overridden in turn by syntax-specific settings.\n{\n\t$0\n}\n"
}
command: new_window
command: set_layout {
    "cells": [[0, 0, 1, 1], [1, 0, 2, 1]], "cols": [0.0, 0.5, 1.0], "rows": [0.0, 1.0]
}
command: open_file {
    "file": "${packages}/Default/Preferences.sublime-settings"
}
command: open_file {
    "contents": "// Settings in here override those in \"Default/Preferences.sublime-settings\",\n// and are overridden in turn by syntax-specific settings.\n{\n\t$0\n}\n",
    "file": "C:\\Users\\Vic\\AppData\\Roaming\\Sublime Text\\Packages\\User\\Preferences.sublime-settings"
}
Unable to open /C/Users/Vic/AppData/Roaming/Sublime Text/Packages/Default/Preferences.sublime-settings
command: exec {"update_annotations_only": true}
command: exec {"update_annotations_only": true}

So it can be seen that the edit_settings command uses the open_file command internally.

Note also the function of the $0 variable in the “default” element. It marks where the cursor will be placed once the text is inserted. When the user has not created any custom settings, there is no <data_path>/Packages/User/Preferences.sublime-settings file so Sublime Text creates one and places this as its content:

// Settings in here override those in "Default/Preferences.sublime-settings",
// and are overridden in turn by syntax-specific settings.
{
    |  <-- cursor is placed here
}

which does not get written to disk until the user saves it.

This is found in Context.sublime-menu (context menu within an open file), creating the “Open Containing Folder…” option:

{ "command": "open_dir", "args": {"dir": "$file_path", "file": "$file_name"}, "caption": "Open Containing Folder…" },

passing the above strings into the “dir” and “file” arguments. It causes the OS’s File Explorer to open and focus placed upon the target file. Nice touch.

The following is from Main.sublime-menu in the Preferences menu:

{
    "command": "edit_settings", "args":
    {
        "base_file": "${packages}/Default/Default ($platform).sublime-keymap",
        "default": "[\n\t$0\n]\n"
    },
    "caption": "Key Bindings"
},
{
    "command": "edit_settings", "args":
    {
        "base_file": "${packages}/Default/Default ($platform).sublime-mousemap",
        "default": "[\n\t$0\n]\n"
    },
    "caption": "Mouse Bindings"
},

It is clear that these are used in a variety of ways: ${packages} and bare $platform, both inside a string.

5.2. Further Reading

A relatively-complete list of commands exists in the Unofficial Documentation Commands Page.