​
CLI as your development tunnel

The Keystone CLI creates a secure tunnel between Keystone’s cloud-based test recorder and your local development environment. This means you can record tests against your local development server, including work-in-progress features on specific branches. Perfect for testing features before they’re deployed or validating changes in your local environment.

​
Quick start workflow

​
1. Start your local development server

# Start your app locally (example)
npm run dev
# App running at http://localhost:3000

​
2. Start the Keystone runner in proxy mode

keystone start --proxy --api-key your-api-key
This creates a secure tunnel that allows Keystone’s cloud Studio to control your local browser and record tests against your local development environment.

​
3. Record tests in Keystone Studio

  1. Go to Keystone Studio
  2. Create a new test and select “Local Development” environment
  3. The cloud recorder will connect through your CLI tunnel
  4. Navigate to http://localhost:3000 (your local app)
  5. Record your test interactions as normal
  6. Tests are saved to the cloud but reference your local environment

​
Development branch testing

​
Testing feature branches

This workflow is perfect for testing features on specific branches: 
# Switch to your feature branch
git checkout feature/new-checkout-flow

# Start your development server
npm run dev

# Start the Keystone tunnel
keystone start --proxy

# Record tests in Keystone Studio against localhost
# Tests capture the new checkout flow from your branch

​
Benefits for development

  • Test before deploy: Validate features before they reach staging
  • Branch-specific tests: Create tests for features in development
  • Local debugging: Debug tests with full access to browser dev tools
  • Fast iteration: No deployment required to test changes

​
Running modes

​
Local mode (direct connection)

keystone start
  • Direct connection from local Keystone Studio
  • Best for: Local development and testing
  • Browser runs on your machine
  • Full access to localhost and private networks

​
Proxy mode (cloud tunnel)

keystone start --proxy --api-key your-api-key
  • Secure tunnel to cloud Studio
  • Best for: Recording tests against local development
  • Cloud-based test management with local execution
  • Team collaboration on local environment tests

​
Common development workflows

​
1. Feature development testing

# Development workflow
git checkout -b feature/user-dashboard
npm run dev
keystone start --proxy

# Record tests in Studio against localhost
# Tests validate new dashboard functionality
# Save tests to run in CI later

​
2. Bug reproduction and testing

# Bug fix workflow  
git checkout -b fix/login-error
npm run dev
keystone start --proxy

# Reproduce the bug in Studio recorder
# Create test that validates the fix
# Run test to confirm fix works

​
3. API integration testing

# API testing workflow
npm run dev:api  # Start local API server
npm run dev      # Start frontend
keystone start --proxy

# Record tests that interact with local API
# Test various API scenarios and error states
# Validate frontend behavior with real API responses

​
CLI commands reference

​
Start the runner

# Basic local runner
keystone start

# Proxy mode for cloud recording
keystone start --proxy --api-key your-api-key

# Custom port
keystone start --port 9224

# Headless mode (no browser UI)
keystone start --headless

# Debug mode (verbose logging)
keystone start --debug

​
Authentication management

# Check current authentication
keystone auth-status

# Log out and re-authenticate
keystone logout
keystone init

​
Environment setup

​
Configure for your project

Create a .env.local file in your project: 
# Keystone CLI configuration
KEYSTONE_API_KEY=your-api-key
KEYSTONE_API_URL=https://api.withkeystone.com

# Your app configuration
NEXT_PUBLIC_API_URL=http://localhost:8000
DATABASE_URL=postgresql://localhost:5432/myapp_dev

​
Project scripts integration

Add CLI commands to your package.json: 
{
  "scripts": {
    "dev": "next dev",
    "test:record": "keystone start --proxy",
    "test:local": "keystone start"
  }
}
Then use them in your workflow: 
npm run dev          # Start development server
npm run test:record  # Start recording tunnel

​
Local capabilities

When running locally, the CLI provides:
  • Visual recording: See exactly what actions are being recorded
  • Real-time execution: Watch tests run with full browser visibility
  • Network capture: Record API calls and responses
  • Console logging: Capture browser console output
  • Screenshot support: Automatic screenshots at each step
  • Local file access: Test file uploads and downloads

​
Limitations to know

  • Same-origin recording: Direct recording only works for localhost
  • Cross-origin sites: Require proxy mode for cloud Studio access
  • Single session: One browser session at a time (multi-session planned)
  • Port requirements: Default port 9223 must be available

​
Troubleshooting

​
Connection issues

# Check if runner is accessible
curl http://localhost:9223/health

# Restart with debug logging
keystone start --debug --proxy

​
Authentication problems

# Verify authentication
keystone auth-status

# Re-authenticate if needed
keystone logout && keystone init

​
Port conflicts

# Use different port
keystone start --port 9224

# Check what's using the port
lsof -i :9223

​
Next steps

Configuration

Advanced configuration and environment variables

Running Tests

Execute tests locally and manage test runs