​
Getting started with Keystone CLI

The Keystone CLI lets you run tests locally, create a tunnel for cloud-based test recording, and integrate testing into your development workflow. Perfect for testing on branches, local development, or when you need more control over the testing environment.

​
Installation

​
Install globally via npm

npm install -g @keystone/cli

​
Initial setup

​
1. Initialize and authenticate

keystone init
This command will:
  • Auto-detect your environment (SSH vs local)
  • Open your browser for authentication (or use device flow for SSH)
  • Store credentials securely in your OS keychain
  • Validate the connection to Keystone

​
2. Authentication options

Browser authentication (default):
  • Opens browser automatically
  • Uses PKCE flow with SHA256 code challenge
  • Stores tokens in OS keychain or encrypted file
Device flow (SSH/headless environments): 
keystone init --no-browser
  • Displays a user code and verification URL
  • Enter the code at the verification URL
  • CLI polls for completion automatically

​
3. Verify installation

keystone auth-status
This shows:
  • Your email and user ID
  • Organization name and ID
  • Token expiration time
  • Granted scopes

​
Configuration options

​
Environment variables

Set these in your shell profile or .env file: 

### Custom API endpoints

If you're running Keystone on-premise or using custom endpoints:

```bash
keystone init --api-url https://your-keystone-api.com --frontend-url https://your-keystone-frontend.com

​
Security and credentials

​
Token storage

Keystone stores authentication tokens securely: Preferred method: OS Keychain
  • macOS: Keychain Access
  • Windows: Windows Credential Store
  • Linux: Secret Service API
Fallback method: Encrypted file
  • Location: ~/.keystone/credentials
  • Encryption: AES-256-GCM
  • Automatic token refresh 5 minutes before expiration

​
Security features

  • PKCE flow: SHA256 code challenge method for OAuth
  • State parameter: CSRF protection in OAuth flow
  • Automatic refresh: Tokens renewed automatically
  • Secure storage: OS-level credential management

​
Troubleshooting installation

​
Common issues

Port already in use: 
keystone start --port 9224
Chrome not found: The CLI auto-detects Chrome/Chromium. If detection fails, ensure Chrome is installed and in your PATH. Authentication failures: 
keystone logout
keystone init
Permission issues: 
sudo npm install -g @keystone/cli

​
Getting help

Check your installation: 
keystone --version
keystone --help
View authentication status: 
keystone auth-status

​
Next steps

CLI Quickstart

Start recording and running tests locally

Configuration

Advanced configuration and environment setup