OpenTester CLI User Guide

March 8, 2026 · View on GitHub

OpenTester provides the opentester command for starting/stopping API and MCP services, plus status and environment checks.

Installation

pip install opentester

Or use the standalone executable:

# Windows
opentester.exe --version

# Linux/Mac
./opentester --version

Available Commands

Service Management

start - Start Services

Start FastAPI and MCP services.

# Start all services (default)
opentester start

# Start only FastAPI
opentester start --api

# Start only MCP
opentester start --mcp

# Custom API port
opentester start --api-port 8080

# Custom MCP port
opentester start --mcp-port 8081

# Daemon mode (detached background mode)
opentester start --daemon

Options:

  • --api - Start only FastAPI server
  • --mcp - Start only MCP server
  • --api-port - Port for API server (default: 8000)
  • --mcp-port - Port for MCP server (default: 8001)
  • --daemon - Start services in detached background mode and return immediately

Runtime behavior:

  • Foreground mode: start keeps the parent process alive until Ctrl+C. Logs are output to console with service prefixes ([API], [MCP]).
  • Daemon mode: Child processes are detached, logs are written to files, and CLI exits after services report readiness.
  • Readiness-based startup: In daemon mode, the CLI waits for services to be fully ready (health check at /health) before exiting.
  • Busy port handling: If a port is already in use, the CLI will report failure and exit with a non-zero status.
  • PID files are written for spawned api and mcp processes in both modes.
Daemon Mode Details

When running with --daemon:

  1. Services start in background processes
  2. CLI waits for health checks to pass (/health endpoint)
  3. Once ready, CLI exits with success status
  4. Logs are written to files instead of console
  5. If ports are busy, the command fails immediately

stop - Stop Services

# Stop all services
opentester stop

# Stop only FastAPI
opentester stop --api

# Stop only MCP
opentester stop --mcp

Options:

  • --api - Stop only FastAPI server
  • --mcp - Stop only MCP server

status - Check Service Status

opentester status

Example output:

OpenTester Status

Service  Status   Info
API      running  PID: 12345
MCP      running  PID: 12346

Status states:

  • running - Service is active and responding to health checks
  • starting - Service was started but health check has not yet passed
  • stale-pid - PID file exists but the process is not running (will be cleaned up automatically)
  • stopped - Service is not running

The status command performs automatic stale PID cleanup. If a PID file exists for a process that is no longer running, the status command detects this as stale-pid and removes the stale PID file.

Environment Check

doctor - Check Environment Configuration

Check Python version, data directory, port availability, etc.

opentester doctor

Example output:

OpenTester Environment Check
═══════════════════════════════════════════════════════════════

✓ Python 3.13+ installed (3.13.0)
✓ Data directory exists (XDG data dir)
✓ PID directory exists (~/.opentester/pids)
✓ Core dependencies installed
✓ Port 8000 available
✓ Port 8001 available

═══════════════════════════════════════════════════════════════
Environment check passed! You can start OpenTester with:
  opentester start

Quick Start

# 1. Check environment
opentester doctor

# 2. Start services
opentester start

# 3. Check status
opentester status

# 4. Stop services
opentester stop

Configuration

Data Directory

OpenTester follows the XDG Base Directory Specification for data storage:

Linux:

  • Data: ~/.local/share/opentester/
  • Config: ~/.config/opentester/

macOS:

  • Data: ~/Library/Application Support/opentester/
  • Config: ~/.config/opentester/

Windows:

  • Data: %LOCALAPPDATA%\opentester\
  • Config: %APPDATA%\opentester\

Directory structure:

<Data Directory>/
├── projects/       # Project data
├── executions/     # Execution records
├── templates/      # Template data
└── logs/           # Log files
    └── daemon/     # Daemon mode service logs

Note: runtime data is XDG-based, but PID files are still stored in ~/.opentester/pids/ (legacy location).

Environment Variables

VariableDescriptionDefault
XDG_DATA_HOMEBase data directoryPlatform-specific
XDG_CONFIG_HOMEBase config directoryPlatform-specific
FASTMCP_HOSTMCP host bind127.0.0.1
FASTMCP_PORTMCP port bind8001

PID Files

PID files are stored in: ~/.opentester/pids/

  • api.pid - FastAPI service process ID
  • mcp.pid - MCP service process ID

Daemon Logs

When running in daemon mode (--daemon), service logs are written to files in the XDG data directory:

  • Location: <XDG_DATA_HOME>/opentester/logs/daemon/
  • API logs: api_YYYYMMDD.log
  • MCP logs: mcp_YYYYMMDD.log

Log retention: Logs older than 7-day retention are automatically cleaned up on each daemon start.

Platform-specific paths:

Linux:

~/.local/share/opentester/logs/daemon/api_20260308.log
~/.local/share/opentester/logs/daemon/mcp_20260308.log

macOS:

~/Library/Application Support/opentester/logs/daemon/api_20260308.log
~/Library/Application Support/opentester/logs/daemon/mcp_20260308.log

Windows:

%LOCALAPPDATA%\opentester\logs\daemon\api_20260308.log
%LOCALAPPDATA%\opentester\logs\daemon\mcp_20260308.log

Troubleshooting

Port Already in Use

# Check port usage
# Windows
netstat -ano | findstr :8000

# Linux/Mac
lsof -i :8000

# Stop the process using the port or use different ports
opentester start --api-port 8002 --mcp-port 8003

When ports are busy, the daemon will fail to start and report which port is in use. Foreground mode will also fail with an error message.

Permission Issues

# Ensure PID directory is writable
# Linux/Mac
mkdir -p ~/.opentester/pids
chmod 755 ~/.opentester/pids

# Windows (PowerShell)
New-Item -ItemType Directory -Path "$env:USERPROFILE\.opentester\pids" -Force

Service Won't Start

# Check detailed errors
opentester doctor

# View logs (foreground mode)
opentester start

# View daemon logs (daemon mode)
# Linux/Mac
tail -f ~/.local/share/opentester/logs/daemon/api_$(date +%Y%m%d).log

# Windows (PowerShell)
Get-Content "$env:LOCALAPPDATA\opentester\logs\daemon\api_$(Get-Date -Format 'yyyyMMdd').log" -Wait

Stale PID Files

If the status command shows stale-pid:

# Status command automatically cleans up stale PID files
opentester status

# If services are still showing stale-pid, you can manually clean up
# Linux/Mac
rm ~/.opentester/pids/*.pid

# Windows (PowerShell)
Remove-Item "$env:USERPROFILE\.opentester\pids\*.pid"

Platform-Specific Commands

Starting Daemon Mode

Linux/Mac (Bash):

opentester start --daemon

Windows (Command Prompt):

opentester.exe start --daemon

Windows (PowerShell):

opentester.exe start --daemon

Viewing Logs

Linux/Mac (Bash):

# View today's API log
tail -f ~/.local/share/opentester/logs/daemon/api_$(date +%Y%m%d).log

# View today's MCP log
tail -f ~/.local/share/opentester/logs/daemon/mcp_$(date +%Y%m%d).log

macOS (if using default shell):

# View today's API log
tail -f ~/Library/Application\ Support/opentester/logs/daemon/api_$(date +%Y%m%d).log

Windows (PowerShell):

# View today's API log
Get-Content "$env:LOCALAPPDATA\opentester\logs\daemon\api_$(Get-Date -Format 'yyyyMMdd').log" -Wait

# View today's MCP log
Get-Content "$env:LOCALAPPDATA\opentester\logs\daemon\mcp_$(Get-Date -Format 'yyyyMMdd').log" -Wait

Checking Port Usage

Linux/Mac:

# Check port 8000
lsof -i :8000

# Check all OpenTester ports
lsof -i :8000,8001

Windows (Command Prompt):

netstat -ano | findstr :8000
netstat -ano | findstr :8001

Windows (PowerShell):

Get-NetTCPConnection -LocalPort 8000
Get-NetTCPConnection -LocalPort 8001

Getting Help

# View all commands
opentester --help

# View specific command help
opentester start --help
opentester stop --help
opentester status --help
opentester doctor --help