​
Basic Usage

The Keystone CLI uses the following syntax for all commands: keystone-runner <command> [options] Image: CLI command structure would go here

​
Commands

​
start

Start the Keystone test runner WebSocket server with various configuration options. Image: Start command interface would go here

​
Options

OptionAliasDescriptionDefault
--port-pWebSocket server port9223
--headlessRun browser in headless modefalse
--debugEnable verbose debug loggingfalse
--proxyEnable proxy mode for cloud Studiofalse
--api-keyAPI key for authentication-
--backend-urlBackend URLhttps://api.withkeystone.com
--base-urlBase URL for relative navigation-
--chrome-pathPath to Chrome executableAuto-detected
--chrome-argsAdditional Chrome arguments-

​
Examples

Local Development: Start with default settings, custom port and debug mode, or with base URL for relative navigation. CI/CD Mode: Run in headless mode with API keys and environment-specific URLs for continuous integration. Proxy Mode: Connect to cloud Studio using API key and backend URL for remote testing. Custom Chrome: Specify custom Chrome executable path and additional browser arguments. Image: Command examples visualization would go here

​
check-chrome

Verify Chrome installation and compatibility. This command checks for Chrome location, version compatibility, and executable permissions. Image: Chrome check output example would go here

​
version

Display the installed Keystone version using either version command or --version flag. Image: Version command output would go here

​
help

Display help information for all commands or specific command details. Image: Help command output would go here

​
Environment Variables

Environment variables can be used instead of CLI options:
VariableCLI OptionDescription
KEYSTONE_API_KEY--api-keyAPI key for authentication
KEYSTONE_API_URL--backend-urlBackend API URL
RUNNER_API_KEY-Runner-specific API key
CHROME_PATH--chrome-pathChrome executable path
PORT--portWebSocket server port
BASE_URL--base-urlBase URL for tests
HEADLESS--headlessRun in headless mode
DEBUG--debugEnable debug logging
Priority order: CLI options > Environment variables > Config file > Defaults

​
Configuration File

Create keystone.config.js in your project root to define default settings for server, browser, test execution, API connections, and recording options. Image: Configuration file structure would go here Configuration sections include:
  • Server: Port and host settings
  • Browser: Headless mode, Chrome path, and browser arguments
  • Test: Base URL, timeouts, retries, and viewport dimensions
  • API: Authentication keys and endpoint URLs
  • Recording: Screenshot, video, network, and console capture settings

​
Advanced Usage

​
Custom Chrome Arguments

Pass multiple Chrome arguments: 
keystone-runner start --chrome-args "--no-sandbox --disable-gpu --window-size=1920,1080"
Common Chrome arguments:
  • --no-sandbox - Disable sandbox (required in Docker)
  • --disable-setuid-sandbox - Disable setuid sandbox
  • --disable-gpu - Disable GPU hardware acceleration
  • --disable-dev-shm-usage - Overcome limited resource problems
  • --disable-web-security - Disable same-origin policy (testing only)
  • --window-size=width,height - Set initial window size
  • --user-data-dir=/path - Use specific Chrome profile

​
Debug Mode

Enable detailed logging: 
# Via CLI flag
keystone-runner start --debug

# Via environment variable
DEBUG=true keystone-runner start

# With specific debug namespace
DEBUG=keystone:* keystone-runner start
Debug output includes:
  • WebSocket message flow
  • Step execution details
  • Browser events
  • Network requests
  • Error stack traces

​
Proxy Mode Details

Proxy mode allows cloud Studio to connect to your local runner: 
# Start in proxy mode
keystone-runner start --proxy --api-key YOUR_API_KEY

# Output
Keystone Runner started in PROXY mode
Connecting to backend: https://api.withkeystone.com
Proxy connection established
Waiting for Studio connections...
The runner will:
  1. Connect to Keystone backend via WebSocket
  2. Authenticate using your API key
  3. Forward messages between Studio and local browser
  4. Handle file provisioning and environment setup

​
Health Check Endpoint

The runner exposes a health check endpoint: 
# Check health
curl http://localhost:9223/health

# Response
{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "sessions": {
    "active": 2,
    "total": 10
  },
  "browser": {
    "connected": true,
    "version": "120.0.6099.109"
  }
}

​
Exit Codes

The CLI uses standard exit codes:
CodeDescription
0Success
1General error
2Chrome not found
3Port already in use
4Authentication failed
5Configuration error

​
Logging

​
Log Levels

Control log verbosity: 
# Error only
LOG_LEVEL=error keystone-runner start

# Info and above (default)
LOG_LEVEL=info keystone-runner start

# Debug (everything)
LOG_LEVEL=debug keystone-runner start

​
Log Format

Logs use structured format: 
[2024-01-20 10:30:45] [INFO] Server started on port 9223
[2024-01-20 10:30:46] [DEBUG] WebSocket connection from ::1
[2024-01-20 10:30:47] [ERROR] Step execution failed: Element not found

​
Log Files

Save logs to file: 
# Redirect output
keystone-runner start > keystone.log 2>&1

# With timestamps
keystone-runner start | ts '[%Y-%m-%d %H:%M:%S]' > keystone.log

​
Tips and Best Practices

  1. Use Configuration Files: For complex setups, use keystone.config.js instead of many CLI flags
  2. Environment-Specific Settings: Use environment variables for sensitive data and environment-specific values
  3. Debug Strategically: Enable debug mode only when troubleshooting to avoid log noise
  4. Port Management: Use dynamic ports in CI to avoid conflicts: 
    PORT=0 keystone-runner start  # Uses random available port
  5. Graceful Shutdown: The runner handles SIGINT and SIGTERM for clean shutdown: 
    # Graceful stop
kill -TERM $(pgrep -f keystone-runner)