Skip to main content

VSCode Command Client

A Python client for communicating with VSCode Command Server extension. Execute VSCode commands remotely via HTTP API.

Installation

pip install vscode-command-client

Quick Start

Python API

from vscode_command_client import VSCodeHTTPClient

# Create client (server must be running)
client = VSCodeHTTPClient(port=3000)

# Check if server is running
status = client.check_status()
print(status)

# Execute VSCode commands
result = client.execute_command("workbench.action.showCommands")
print(result)

# Get available commands
commands = client.get_commands()
print(f"Found {commands['count']} commands")

# Get server info
info = client.get_server_info()
print(f"Workspace: {info.get('workspace')}")

# Connection recovery features
if not client.is_server_running():
    # Try to reconnect
    reconnect_result = client.reconnect()
    print(f"Reconnect: {reconnect_result}")
    
    # Or restart the server
    restart_result = client.restart_server()
    print(f"Restart: {restart_result}")

# Comprehensive health check
health = client.health_check()
print(f"Health: {health}")

Command Line Interface

# Check server status
vscode-client status

# Get server info
vscode-client info

# Execute a command
vscode-client execute workbench.action.showCommands

# Execute with retry
vscode-client execute workbench.action.showCommands --retry

# List available commands
vscode-client commands --limit 10

# Filter commands
vscode-client commands --filter "terminal"

# Wait for server to start
vscode-client wait --max-wait 60

# Connection recovery commands
vscode-client reconnect --max-attempts 3 --wait-time 2
vscode-client restart-server
vscode-client health-check

# Use different port with auto-retry
vscode-client --port 3001 --auto-retry status

# Get JSON output
vscode-client --json info

Features

  • ✅ Simple API: Easy-to-use Python client
  • 🚀 CLI Tool: Command-line interface included
  • ⏰ Timeout Support: Configurable request timeouts
  • 🔄 Session Management: Persistent HTTP sessions
  • 📊 Server Monitoring: Check status and wait for availability
  • 🛠️ Connection Recovery: Reconnect and restart capabilities
  • 🏥 Health Checks: Comprehensive server health monitoring
  • 🔁 Auto Retry: Automatic retry on connection failures
  • 🎯 Type Hints: Full type annotations
  • 🛡️ Error Handling: Robust error handling

Connection Recovery

Auto Retry

# Enable auto-retry for all requests
client = VSCodeHTTPClient(auto_retry=True)

# Or for specific commands
result = client.execute_command("some.command", retry=True)

Manual Recovery

# Reconnect to server
reconnect_result = client.reconnect(max_attempts=5, wait_time=2)

# Restart the VSCode extension server
restart_result = client.restart_server()

# Comprehensive health check
health = client.health_check()

CLI Recovery Commands

# Reconnect with custom settings
vscode-client reconnect --max-attempts 5 --wait-time 3

# Restart the server extension
vscode-client restart-server

# Check overall health
vscode-client health-check

# Use auto-retry globally
vscode-client --auto-retry execute workbench.action.showCommands

API Reference

VSCodeHTTPClient

Constructor

VSCodeHTTPClient(port=3000, host="localhost", timeout=30, auto_retry=False)
  • port: Server port (default: 3000)
  • host: Server host (default: localhost)
  • timeout: Request timeout in seconds (default: 30)
  • auto_retry: Enable automatic retry on connection failure (default: False)

Methods

check_status() -> Dict[str, Any]

Check if the server is running.

execute_command(command: str, args: List[Any] = None, retry: bool = None) -> Dict[str, Any]

Execute a VSCode command with optional arguments and retry override.

get_commands() -> Dict[str, Any]

Get list of all available VSCode commands.

get_server_info() -> Dict[str, Any]

Get server information (port, PID, workspace).

is_server_running() -> bool

Quick check if server is responding.

wait_for_server(max_wait: int = 30, check_interval: float = 1.0) -> bool

Wait for server to become available.

reconnect(max_attempts: int = 5, wait_time: int = 2) -> Dict[str, Any]

Attempt to reconnect to the server.

restart_server() -> Dict[str, Any]

Restart the VSCode Command Server extension.

health_check() -> Dict[str, Any]

Comprehensive health check of server connection.

Context Manager Support

with VSCodeHTTPClient() as client:
    result = client.execute_command("workbench.action.toggleTerminal")
    print(result)

Common VSCode Commands

# File operations
client.execute_command("workbench.action.files.newUntitledFile")
client.execute_command("workbench.action.files.save")

# Editor operations
client.execute_command("workbench.action.closeActiveEditor")
client.execute_command("workbench.action.splitEditor")

# Terminal operations
client.execute_command("workbench.action.terminal.toggleTerminal")
client.execute_command("workbench.action.terminal.new")

# View operations
client.execute_command("workbench.action.showCommands")
client.execute_command("workbench.action.openSettings")
client.execute_command("workbench.action.quickOpen")

Error Handling with Recovery

try:
    result = client.execute_command("some.command")
    if result["success"]:
        print("Command executed successfully")
    else:
        print(f"Command failed: {result['error']}")
        
        # Try recovery if connection failed
        if "connection" in result["error"].lower():
            print("Attempting to reconnect...")
            if client.reconnect()["success"]:
                # Retry the command
                result = client.execute_command("some.command")
                print(f"Retry result: {result}")
            
except Exception as e:
    print(f"Connection error: {e}")
    # Try restarting the server
    restart_result = client.restart_server()
    print(f"Restart attempt: {restart_result}")

Requirements

  • Python 3.8+
  • requests >= 2.25.0
  • VSCode Command Server extension running

License

MIT License

Metadata

Release files for vscode-command-client 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vscode-command-client 1.0.0
File Size Uploaded Provenance Actions
vscode_command_client-1.0.0.tar.gz 7.4 kB Without provenance Details for vscode_command_client-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vscode-command-client 1.0.0
File Interpreter ABI Platform Actions
vscode_command_client-1.0.0-py3-none-any.whl Python 3 none any Details for vscode_command_client-1.0.0-py3-none-any.whl

Total release size: 17.3 kB

Release files / vscode_command_client-1.0.0.tar.gz

Download URL vscode_command_client-1.0.0.tar.gz
Size 7.4 kB
Tags Source
SHA-256 checksum
How to use checksums
038392a8abd2c9b7a3aaa26238b158736843c05c1b5be7daebad474322c824eb
BLAKE2b-256 checksum
How to use checksums
eebca362b20b2ebd6aee7947bfbcddb2315b1ebae4a17bcf7657683bd3c9ca1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.10.0

Release files / vscode_command_client-1.0.0-py3-none-any.whl

Download URL vscode_command_client-1.0.0-py3-none-any.whl
Size 10.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
79897fc12e5b1062201d88ca7ed3165720328701e057cadde1cdc53f36e3f06e
BLAKE2b-256 checksum
How to use checksums
d1fdc29701ca28dcaf34c12e31510c41133560c0a7f9d1de3003c62d48602778
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.10.0

Security for vscode-command-client 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page