Commands API

The Commands API allows you to register and execute commands in VS Code. Commands are functions with unique identifiers that can be invoked from the Command Palette, keyboard shortcuts, menus, or programmatically.

Namespace

vscode.commands

All command-related functionality is available through the commands namespace.

Core Functions

registerCommand

function registerCommand(
    command: string,
    callback: (...args: any[]) => any,
    thisArg?: any
): Disposable

string

required

A unique identifier for the command

function

required

The command handler function that will be executed

any

The this context used when invoking the handler

Disposable

Disposable that unregisters the command when disposed

Example

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    // Register a simple command
    let disposable = vscode.commands.registerCommand('extension.sayHello', () => {
        vscode.window.showInformationMessage('Hello World!');
    });
    
    context.subscriptions.push(disposable);
    
    // Register command with arguments
    let greetCommand = vscode.commands.registerCommand(
        'extension.greet',
        (name: string) => {
            vscode.window.showInformationMessage(`Hello, ${name}!`);
        }
    );
    
    context.subscriptions.push(greetCommand);
}

Registering a command with an existing identifier will cause an error. Ensure your command IDs are unique.

registerTextEditorCommand

function registerTextEditorCommand(
    command: string,
    callback: (textEditor: TextEditor, edit: TextEditorEdit, ...args: any[]) => void,
    thisArg?: any
): Disposable

string

required

Unique identifier for the command

function

required

Handler with access to the active TextEditor and TextEditorEdit builder

any

The this context for the handler

Example

const command = vscode.commands.registerTextEditorCommand(
    'extension.transformText',
    (textEditor: vscode.TextEditor, edit: vscode.TextEditorEdit) => {
        const document = textEditor.document;
        const selection = textEditor.selection;
        
        // Get selected text
        const text = document.getText(selection);
        
        // Transform and replace
        edit.replace(selection, text.toUpperCase());
    }
);

context.subscriptions.push(command);

The edit builder is only valid during callback execution. Changes are applied atomically when the callback completes.

executeCommand

Execute a command programmatically.

function executeCommand<T = unknown>(
    command: string,
    ...rest: any[]
): Thenable<T>

string

required

Identifier of the command to execute

any[]

Parameters passed to the command handler

Thenable<T>

A thenable that resolves to the command’s return value

Example

// Execute a built-in command
await vscode.commands.executeCommand('workbench.action.files.save');

// Execute your own command with arguments
const result = await vscode.commands.executeCommand(
    'extension.calculate',
    10,
    20
);
console.log('Result:', result);

// Open a file
await vscode.commands.executeCommand(
    'vscode.open',
    vscode.Uri.file('/path/to/file.txt')
);

Primitive Types
VS Code Types

// Only primitive types are allowed for built-in commands
await vscode.commands.executeCommand(
    'editor.action.insertSnippet',
    { snippet: 'console.log($1);' }
);

// Position, Range, Uri, and Location are also allowed
await vscode.commands.executeCommand(
    'editor.action.goToLocations',
    document.uri,
    new vscode.Position(10, 5),
    locations
);

getCommands

Retrieve the list of all available commands.

function getCommands(filterInternal?: boolean): Thenable<string[]>

boolean

default:"false"

Set to true to exclude internal commands (those starting with underscore)

Thenable<string[]>

List of command identifiers

Example

// Get all commands including internal
const allCommands = await vscode.commands.getCommands();
console.log(`Total commands: ${allCommands.length}`);

// Get only public commands
const publicCommands = await vscode.commands.getCommands(true);
const extensionCommands = publicCommands.filter(cmd => 
    cmd.startsWith('extension.')
);
console.log('Extension commands:', extensionCommands);

Command Interface

Commands are referenced using the Command interface:

interface Command {
    title: string;
    command: string;
    tooltip?: string;
    arguments?: any[];
}

string

required

Human-readable title displayed in the UI

string

required

The identifier of the command handler

Optional tooltip shown when hovering over the command

any[]

Arguments passed to the command handler when invoked

Usage Example

// In a CodeLens
const codeLens = new vscode.CodeLens(range, {
    title: 'Run Test',
    command: 'extension.runTest',
    arguments: [testId, testFile]
});

// In a tree item
const treeItem = new vscode.TreeItem('Item');
treeItem.command = {
    title: 'Open File',
    command: 'vscode.open',
    arguments: [uri]
};

Package.json Contributions

Declare commands in your package.json to make them available in the Command Palette:

package.json

{
  "contributes": {
    "commands": [
      {
        "command": "extension.helloWorld",
        "title": "Hello World",
        "category": "My Extension",
        "icon": "$(rocket)"
      },
      {
        "command": "extension.openSettings",
        "title": "Open Settings",
        "category": "My Extension",
        "enablement": "workspaceFolderCount > 0"
      }
    ],
    "keybindings": [
      {
        "command": "extension.helloWorld",
        "key": "ctrl+shift+h",
        "mac": "cmd+shift+h",
        "when": "editorTextFocus"
      }
    ],
    "menus": {
      "editor/context": [
        {
          "command": "extension.transform",
          "when": "editorHasSelection",
          "group": "1_modification"
        }
      ]
    }
  }
}

Built-in Commands

VS Code provides many built-in commands you can execute:

// Save the active file
await vscode.commands.executeCommand('workbench.action.files.save');

// Format document
await vscode.commands.executeCommand('editor.action.formatDocument');

// Toggle sidebar
await vscode.commands.executeCommand('workbench.action.toggleSidebarVisibility');

// Open a file
await vscode.commands.executeCommand(
    'vscode.open',
    vscode.Uri.file('/path/to/file')
);

// Reveal file in explorer
await vscode.commands.executeCommand(
    'revealFileInOS',
    vscode.Uri.file('/path/to/file')
);

// Open Git source control
await vscode.commands.executeCommand('workbench.view.scm');

// Commit changes
await vscode.commands.executeCommand('git.commit');

Advanced Patterns

Conditional Command Registration

if (someCondition) {
    const disposable = vscode.commands.registerCommand(
        'extension.conditionalCommand',
        () => {
            // Command implementation
        }
    );
    context.subscriptions.push(disposable);
}

Command Chaining

vscode.commands.registerCommand('extension.workflow', async () => {
    // Execute multiple commands in sequence
    await vscode.commands.executeCommand('workbench.action.files.save');
    await vscode.commands.executeCommand('editor.action.formatDocument');
    await vscode.commands.executeCommand('workbench.action.files.saveAll');
    
    vscode.window.showInformationMessage('Workflow completed!');
});

Error Handling

vscode.commands.registerCommand('extension.safeCommand', async () => {
    try {
        const result = await vscode.commands.executeCommand('some.command');
        return result;
    } catch (error) {
        vscode.window.showErrorMessage(`Command failed: ${error.message}`);
        return null;
    }
});

Best Practices

Command Naming

Use a consistent prefix (e.g., myExtension.commandName)
Choose descriptive, action-oriented names
Avoid generic names that might conflict
Document all public commands

Performance

Keep command handlers lightweight
Use async/await for long-running operations
Show progress indicators for slow operations
Don’t block the UI thread

User Experience

Provide clear feedback when commands execute
Handle errors gracefully with user-friendly messages
Support undo/redo when modifying text
Use appropriate keyboard shortcuts

Common Use Cases

Transform Selected Text

vscode.commands.registerTextEditorCommand(
    'extension.uppercase',
    (editor, edit) => {
        const selections = editor.selections;
        
        for (const selection of selections) {
            const text = editor.document.getText(selection);
            edit.replace(selection, text.toUpperCase());
        }
    }
);

Open External URL

vscode.commands.registerCommand('extension.openDocs', () => {
    vscode.env.openExternal(
        vscode.Uri.parse('https://example.com/docs')
    );
});

Create New File with Content

vscode.commands.registerCommand('extension.newTemplate', async () => {
    const doc = await vscode.workspace.openTextDocument({
        content: '// Template\n',
        language: 'javascript'
    });
    await vscode.window.showTextDocument(doc);
});

Text Editor API - Manipulate text in editors
Window API - Show notifications and dialogs
Workspace API - Access workspace resources

Extension API

Core Services

Platform APIs

Commands API

Commands API

Namespace

Core Functions

registerCommand

Example

registerTextEditorCommand

Example

executeCommand

Example

getCommands

Example

Command Interface

Usage Example

Package.json Contributions

Built-in Commands

Advanced Patterns

Conditional Command Registration

Command Chaining

Error Handling

Best Practices

Common Use Cases

Transform Selected Text

Open External URL

Create New File with Content

​Commands API

​Namespace

​Core Functions

​registerCommand

​Example

​registerTextEditorCommand

​Example

​executeCommand

​Example

​getCommands

​Example

​Command Interface

​Usage Example

​Package.json Contributions

​Built-in Commands

​Advanced Patterns

​Conditional Command Registration

​Command Chaining

​Error Handling

​Best Practices

​Common Use Cases

​Transform Selected Text

​Open External URL

​Create New File with Content

​Related APIs

Commands API

Namespace

Core Functions

registerCommand

Example

registerTextEditorCommand

Example

executeCommand

Example

getCommands

Example

Command Interface

Usage Example

Package.json Contributions

Built-in Commands

Advanced Patterns

Conditional Command Registration

Command Chaining

Error Handling

Best Practices

Common Use Cases

Transform Selected Text

Open External URL

Create New File with Content

Related APIs