CLI Configuration

Configuration overview

The Keystone CLI offers flexible configuration through environment variables, command-line options, and configuration files. This allows you to customize the CLI for different projects, environments, and team workflows.

Environment variables

Core configuration

Set these environment variables in your shell profile, .env file, or CI environment:

# API endpoints
KEYSTONE_API_URL="https://api.withkeystone.com"
KEYSTONE_FRONTEND_URL="https://app.withkeystone.com"

# Authentication
KEYSTONE_API_KEY="your-api-key-here"

# Local runner settings
KEYSTONE_RUNNER_PORT="9223"
KEYSTONE_HEADLESS="false"
KEYSTONE_DEBUG="false"

# File and directory settings
TEST_FILES_DIR="./tests"
KEYSTONE_CREDENTIALS_PATH="~/.keystone/credentials"

Auto-detection variables

The CLI automatically detects certain environment conditions:

# SSH connection detection (auto-enables device flow)
SSH_CONNECTION="auto-detected"

# CI environment detection
CI="true"
GITHUB_ACTIONS="true"
GITLAB_CI="true"

Custom backend URLs

For on-premise or custom Keystone installations:

# Custom Keystone instance
KEYSTONE_API_URL="https://keystone.yourcompany.com/api"
KEYSTONE_FRONTEND_URL="https://keystone.yourcompany.com"

# Local development (if running Keystone locally)
KEYSTONE_API_URL="http://localhost:8000"
KEYSTONE_FRONTEND_URL="http://localhost:3000"

Command-line options

Global options

Available for all commands:

# Help and version
keystone --help
keystone --version

# Custom API URL for all commands
keystone --api-url https://custom-api.com <command>

Init command options

# Browser vs device flow
keystone init                                    # Browser auth (default)
keystone init --no-browser                      # Device flow

# Custom endpoints
keystone init --api-url https://api.custom.com
keystone init --frontend-url https://app.custom.com

# Combined
keystone init --no-browser --api-url https://api.custom.com

Start command options

# Basic runner options
keystone start                           # Default local mode
keystone start --port 9224              # Custom port
keystone start --headless               # No browser UI
keystone start --debug                  # Verbose logging

# Proxy mode options
keystone start --proxy                  # Enable proxy mode
keystone start --proxy --api-key xyz    # With API key
keystone start --backend-url https://...# Custom backend

# Combined options
keystone start --proxy --headless --debug --port 9224

Auth commands options

# Check authentication status
keystone auth-status
keystone auth-status --api-url https://custom-api.com

# Logout options
keystone logout                         # Interactive confirmation
keystone logout -y                      # Skip confirmation
keystone logout --yes                   # Skip confirmation (long form)

Project configuration

.keystonerc file

Create a .keystonerc file in your project root for project-specific settings:

{
  "apiUrl": "https://api.withkeystone.com",
  "frontendUrl": "https://app.withkeystone.com",
  "runner": {
    "port": 9223,
    "headless": false,
    "debug": false,
    "proxy": true
  },
  "testFilesDir": "./tests",
  "environments": {
    "development": {
      "baseUrl": "http://localhost:3000",
      "apiKey": "${KEYSTONE_API_KEY}"
    },
    "staging": {
      "baseUrl": "https://staging.example.com",
      "apiKey": "${KEYSTONE_STAGING_API_KEY}"
    }
  }
}

Package.json scripts

Integrate CLI commands into your project workflow:

{
  "scripts": {
    "dev": "next dev",
    "test": "jest",
    "test:e2e": "keystone start --proxy",
    "test:record": "keystone start --proxy --debug",
    "test:local": "keystone start --headless",
    "keystone:auth": "keystone auth-status",
    "keystone:setup": "keystone init"
  }
}

Docker configuration

For containerized development:

# Dockerfile
FROM node:18-slim

# Install Chrome
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
    && echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list \
    && apt-get update \
    && apt-get install -y google-chrome-stable

# Install Keystone CLI
RUN npm install -g @keystone/cli

# Set environment variables
ENV KEYSTONE_HEADLESS=true
ENV KEYSTONE_RUNNER_PORT=9223

EXPOSE 9223

Authentication configuration

Credential storage

Keystone stores credentials securely using OS-level systems: macOS: Keychain Access

# View stored credentials
security find-generic-password -s "keystone-cli"

Windows: Windows Credential Store

# View with Windows Credential Manager

Linux: Secret Service API (libsecret)

# Fallback to encrypted file if Secret Service unavailable

Manual credential management

# Check current credentials
keystone auth-status

# Force re-authentication
keystone logout && keystone init

# Clear credentials manually
rm -rf ~/.keystone/credentials

CI/CD authentication

For automated environments:

# Use API key directly
export KEYSTONE_API_KEY="your-api-key"
keystone start --proxy

# Or use device flow in CI
keystone init --no-browser

Network and proxy configuration

Corporate networks

For environments with proxy servers or restricted networks:

# HTTP proxy
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# Bypass proxy for localhost
export NO_PROXY="localhost,127.0.0.1,.local"

Firewall configuration

Ensure these ports are accessible:

Outbound 443: HTTPS to Keystone API
Outbound 80: HTTP redirects
Inbound 9223: CLI runner (configurable)
Local browser: Chrome/Chromium access

SSL/TLS configuration

For custom SSL certificates:

# Custom CA bundle
export NODE_EXTRA_CA_CERTS="/path/to/ca-bundle.crt"

# Disable SSL verification (not recommended)
export NODE_TLS_REJECT_UNAUTHORIZED="0"

Development configuration

Multi-project setup

Manage multiple projects with different configurations:

# Project A
cd ~/projects/app-a
export KEYSTONE_API_KEY="project-a-key"
keystone start --proxy --port 9223

# Project B  
cd ~/projects/app-b
export KEYSTONE_API_KEY="project-b-key"
keystone start --proxy --port 9224

Team configuration

Share configuration across team members:

# .env.example (committed to repo)
KEYSTONE_API_URL=https://api.withkeystone.com
KEYSTONE_API_KEY=your-api-key-here
KEYSTONE_RUNNER_PORT=9223

# .env.local (gitignored, individual settings)
KEYSTONE_API_KEY=actual-api-key
KEYSTONE_DEBUG=true

Troubleshooting configuration

Debug configuration loading

# Show effective configuration
keystone start --debug

# Check environment variables
env | grep KEYSTONE

Common configuration issues

API key not found:

# Set API key
export KEYSTONE_API_KEY="your-key"
# Or use init to set up authentication
keystone init

Port conflicts:

# Check port usage
lsof -i :9223
# Use different port
keystone start --port 9224

Chrome not found:

# Check Chrome installation
which google-chrome
which chromium-browser
# Install Chrome if missing

Configuration validation

Health check

Verify your configuration:

# Start runner and check health
keystone start &
curl http://localhost:9223/health

# Check authentication
keystone auth-status

Configuration test

# Test proxy mode connection
keystone start --proxy --debug

# Verify API connectivity
keystone auth-status --api-url $KEYSTONE_API_URL

Getting Started

Commands

CLI Configuration

Configuration overview

Environment variables

Core configuration

Auto-detection variables

Custom backend URLs

Command-line options

Global options

Init command options

Start command options

Auth commands options

Project configuration

.keystonerc file

Package.json scripts

Docker configuration

Authentication configuration

Credential storage

Manual credential management

CI/CD authentication

Network and proxy configuration

Corporate networks

Firewall configuration

SSL/TLS configuration

Development configuration

Multi-project setup

Team configuration

Troubleshooting configuration

Debug configuration loading

Common configuration issues

Configuration validation

Health check

Configuration test

Next steps

Running Tests

Debugging

Getting Started

Commands

​Configuration overview

​Environment variables

​Core configuration

​Auto-detection variables

​Custom backend URLs

​Command-line options

​Global options

​Init command options

​Start command options

​Auth commands options

​Project configuration

​.keystonerc file

​Package.json scripts

​Docker configuration

​Authentication configuration

​Credential storage

​Manual credential management

​CI/CD authentication

​Network and proxy configuration

​Corporate networks

​Firewall configuration

​SSL/TLS configuration

​Development configuration

​Multi-project setup

​Team configuration

​Troubleshooting configuration

​Debug configuration loading

​Common configuration issues

​Configuration validation

​Health check

​Configuration test

​Next steps

Running Tests

Debugging

Configuration overview

Environment variables

Core configuration

Auto-detection variables

Custom backend URLs

Command-line options

Global options

Init command options

Start command options

Auth commands options

Project configuration

.keystonerc file

Package.json scripts

Docker configuration

Authentication configuration

Credential storage

Manual credential management

CI/CD authentication

Network and proxy configuration

Corporate networks

Firewall configuration

SSL/TLS configuration

Development configuration

Multi-project setup

Team configuration

Troubleshooting configuration

Debug configuration loading

Common configuration issues

Configuration validation

Health check

Configuration test

Next steps