Run

Stoobly Main CLI Commands - Questions & Answers

The main CLI provides core commands for running the Stoobly agent, initializing contexts, and performing quick record/mock operations without starting the full proxy server.

---

Getting Started

Q: How do I check the Stoobly agent version?

A: Use the --version flag to display the installed version.

Example:

stoobly-agent --version

Q: How do I get help for any command?

A: Use --help or -h after any command to see detailed usage information.

Example:

# Main help
stoobly-agent --help

# Command-specific help
stoobly-agent run --help
stoobly-agent record --help
stoobly-agent mock --help

---

Initializing Stoobly

Q: How do I initialize a new Stoobly context?

A: Use the init command to create a new .stoobly directory with necessary configuration files.

Example:

# Initialize in current directory
stoobly-agent init

# Creates: .stoobly/ directory with database and configuration

Q: What does init create?

A: The init command creates the .stoobly directory structure including database, configuration files, and necessary subdirectories.

Example:

stoobly-agent init

# Created structure:
# .stoobly/
# ├── db/              # Database files
# ├── ca_certs/        # CA certificates
# ├── certs/           # SSL certificates
# ├── logs/            # Log files
# └── config.yml       # Configuration

Q: When should I run init?

A: Run init when setting up Stoobly in a new project directory or when you want to create a fresh Stoobly context.

Example:

# New project setup
mkdir my-project
cd my-project
stoobly-agent init

---

Running the Agent

Q: How do I start Stoobly with both proxy and UI?

A: Use the run command without any flags to start both the proxy server and web UI.

Example:

stoobly-agent run

# Proxy: http://localhost:8080
# UI: http://localhost:4200

Q: How do I run Stoobly in headless mode (proxy only)?

A: Use the --headless flag to disable the UI and run only the proxy.

Example:

stoobly-agent run --headless

# Only proxy runs on http://localhost:8080

Q: How do I run Stoobly without the proxy (UI only)?

A: Use the --proxyless flag to run only the web UI.

Example:

stoobly-agent run --proxyless

# Only UI runs on http://localhost:4200

Q: How do I run Stoobly on custom ports?

A: Use --proxy-port and --ui-port to specify custom ports.

Example:

# Custom ports
stoobly-agent run --proxy-port 9090 --ui-port 5000

# Proxy: http://localhost:9090
# UI: http://localhost:5000

Q: How do I run Stoobly on a specific host/interface?

A: Use --proxy-host and --ui-host to bind to specific network interfaces.

Example:

# Bind to all interfaces (default)
stoobly-agent run --proxy-host 0.0.0.0 --ui-host 0.0.0.0

# Bind to localhost only
stoobly-agent run --proxy-host 127.0.0.1 --ui-host 127.0.0.1

# Bind to specific IP
stoobly-agent run --proxy-host 192.168.1.100

Q: How do I run Stoobly in detached/background mode?

A: Use the --detached flag with a file path to redirect output and run in the background.

Example:

# Run in background
stoobly-agent run --detached /tmp/stoobly.log

# Returns PID
# 12345

# View logs
tail -f /tmp/stoobly.log

# Stop later
kill 12345

Q: How do I enable intercept mode on startup?

A: Use the --intercept flag to activate interception immediately.

Example:

# Enable intercept on startup
stoobly-agent run --intercept

# With specific mode
stoobly-agent run --intercept --intercept-mode mock
stoobly-agent run --intercept --intercept-mode record

Q: How do I set the intercept mode on startup?

A: Use the --intercept-mode option with one of: mock, record, replay, test.

Example:

# Start with mock mode
stoobly-agent run --intercept --intercept-mode mock

# Start with record mode
stoobly-agent run --intercept --intercept-mode record

# Start with test mode
stoobly-agent run --intercept --intercept-mode test

---

Logging and Debugging

Q: How do I increase logging verbosity?

A: Use the --log-level option to control log output detail.

Example:

# Debug level (most verbose)
stoobly-agent run --log-level debug

# Info level (default)
stoobly-agent run --log-level info

# Warning level
stoobly-agent run --log-level warning

# Error level (least verbose)
stoobly-agent run --log-level error

Q: How do I control proxy flow detail output?

A: Use the --flow-detail option with levels 0-4.

Example:

# Level 0: No output
stoobly-agent run --flow-detail 0

# Level 1: Shortened URL + status code (default)
stoobly-agent run --flow-detail 1

# Level 2: Full URL + status + headers
stoobly-agent run --flow-detail 2

# Level 3: Level 2 + truncated response content
stoobly-agent run --flow-detail 3

# Level 4: Everything (no truncation)
stoobly-agent run --flow-detail 4

Q: How do I enable request logging?

A: Use the --request-log-enable flag to log all intercepted requests.

Example:

# Enable request logging
stoobly-agent run --request-log-enable

# With specific log level
stoobly-agent run --request-log-enable --request-log-level debug

# Without truncating log on startup
stoobly-agent run --request-log-enable --request-log-truncate=false

Q: How do I view the intercepted requests log?

A: Use the request log list command while the agent is running or after.

Example:

# Start with logging
stoobly-agent run --request-log-enable

# In another terminal, view logs
stoobly-agent request log list

---

SSL/TLS Configuration

Q: How do I specify a custom CA certificates directory?

A: Use the --ca-certs-dir-path option to set the CA certificate location.

Example:

stoobly-agent run --ca-certs-dir-path ~/.stoobly/ca_certs

Q: How do I use custom SSL certificates?

A: Use the --certs option to provide custom certificate files.

Example:

# Single domain certificate
stoobly-agent run --certs "example.com=/path/to/cert.pem"

# Wildcard certificate
stoobly-agent run --certs "*.example.com=/path/to/wildcard.pem"

# Multiple certificates
stoobly-agent run \
  --certs "api.example.com=/path/to/api-cert.pem" \
  --certs "app.example.com=/path/to/app-cert.pem"

Q: How do I provide a passphrase for encrypted certificates?

A: Use the --cert-passphrase option (note: visible in process list, prefer config file).

Example:

stoobly-agent run \
  --certs "example.com=/path/to/encrypted-cert.pem" \
  --cert-passphrase "my-secret-passphrase"

Q: How do I disable SSL certificate verification?

A: Use the --ssl-insecure flag to skip upstream SSL verification (use with caution).

Example:

# Disable SSL verification
stoobly-agent run --ssl-insecure

# Useful for self-signed certificates in development

---

Proxy Modes

Q: What proxy modes are available?

A: Stoobly supports regular, transparent, socks5, reverse, and upstream proxy modes.

Example:

# Regular proxy (default)
stoobly-agent run --proxy-mode regular

# Transparent proxy
stoobly-agent run --proxy-mode transparent

# SOCKS5 proxy
stoobly-agent run --proxy-mode socks5

# Reverse proxy
stoobly-agent run --proxy-mode "reverse:https://api.example.com"

# Upstream proxy
stoobly-agent run --proxy-mode "upstream:http://corporate-proxy:3128"

Q: How do I set up a reverse proxy?

A: Use the reverse proxy mode with the target host specification.

Example:

# Reverse proxy to backend
stoobly-agent run --proxy-mode "reverse:https://api.backend.com"

# All requests to proxy will be forwarded to api.backend.com
curl http://localhost:8080/users
# Actually requests: https://api.backend.com/users

Q: How do I use an upstream proxy?

A: Use the upstream proxy mode to chain through another proxy.

Example:

# Chain through corporate proxy
stoobly-agent run --proxy-mode "upstream:http://proxy.corporate.com:8080"

---

Lifecycle Hooks

Q: How do I use lifecycle hooks with the agent?

A: Use the --lifecycle-hooks-path option to specify a Python script with custom hooks.

Example:

# Create hooks script
cat > hooks.py << 'EOF'
def before_request(context):
    # Modify request before sending
    context.request.headers['X-Custom-Header'] = 'value'
    return context

def after_response(context):
    # Process response
    print(f"Response status: {context.response.status_code}")
    return context
EOF

# Run with hooks
stoobly-agent run --lifecycle-hooks-path ./hooks.py

---

Mocking and Response Fixtures

Q: How do I use response fixtures for mocking?

A: Use the --response-fixtures-path option to provide YAML files with mock responses.

Example:

# Create fixtures file
cat > fixtures.yml << 'EOF'
- GET:
    /users/d+?:
      headers: {}
      path: <RELATIVE-PATH-TO-TO-RESPONSE-FILE>
      status_code: 200
- POST:
    /users:
      headers: {}
      path: <RELATIVE-PATH-TO-TO-RESPONSE-FILE>
      status_code: 200
EOF

# Run with fixtures
stoobly-agent run --response-fixtures-path ./fixtures.yml

Q: How do I serve static files for mocking?

A: Use the --public-directory-path option to serve files from a directory.

Example:

# Create public directory
mkdir public
echo '{"data": "test"}' > public/test.json

# Run with public directory
stoobly-agent run --public-directory-path ./public

# Access: http://localhost:8080/test.json

Q: How do I specify origin for fixtures and public directories?

A: Use the format <PATH>:<ORIGIN> to match specific origins.

Example:

stoobly-agent run \
  --response-fixtures-path "./fixtures.yml:https://api.example.com" \
  --public-directory-path "./public:https://cdn.example.com"

---

Header Modification

Q: How do I modify request headers?

A: Use the --modify-headers option with header modification patterns.

Example:

# Add header to all requests
stoobly-agent run --modify-headers "/Authorization/Bearer token123"

# Remove header
stoobly-agent run --modify-headers "/X-Debug-Token/"

# Modify specific path
stoobly-agent run --modify-headers "/~u /api/.*//X-Custom/value"

# Multiple modifications
stoobly-agent run \
  --modify-headers "/Authorization/Bearer token" \
  --modify-headers "/X-API-Key/abc123"

---

Quick Record Command

Q: How do I quickly record a single request without starting the agent?

A: Use the record command to make a request and store it.

Example:

# Record GET request
stoobly-agent record https://api.example.com/users

# Record POST request
stoobly-agent record -X POST -d '{"name":"John"}' https://api.example.com/users

# Record with custom headers
stoobly-agent record -H "Authorization: Bearer token" https://api.example.com/profile

Q: How do I record a request to a scenario?

A: Use the --scenario-key option to add the recorded request to a scenario.

Example:

# Record to scenario
stoobly-agent record https://api.example.com/users --scenario-key "<SCENARIO-KEY>"

Q: How do I save recorded response to a file?

A: Use the -o or --output option to write the response.

Example:

# Save response to file
stoobly-agent record https://api.example.com/users -o response.json

# View the file
cat response.json

Q: How do I format the recorded response output?

A: Use the --format option to control output format.

Example:

# Raw HTTP format
stoobly-agent record https://api.example.com/users --format raw

Q: How do I record requests with lifecycle hooks?

A: Use the --lifecycle-hooks-path option with the record command.

Example:

stoobly-agent record https://api.example.com/users --lifecycle-hooks-path ./hooks.py

---

Quick Mock Command

Q: How do I quickly mock a request without starting the agent?

A: Use the mock command to replay a previously recorded request.

Example:

# Mock a URL (must have been recorded before)
stoobly-agent mock https://api.example.com/users

Q: How do I mock with custom headers?

A: Use the -H flag to add custom headers to the mock request.

Example:

stoobly-agent mock -H "Authorization: Bearer token" https://api.example.com/profile

Q: How do I mock a POST request?

A: Use -X POST and -d for the request body.

Example:

stoobly-agent mock -X POST -d '{"id":123}' https://api.example.com/users/search

Q: How do I mock with response fixtures?

A: Use the --response-fixtures-path option to provide mock data.

Example:

stoobly-agent mock https://api.example.com/users --response-fixtures-path ./fixtures.yml

Q: How do I mock with public directory files?

A: Use the --public-directory-path option to serve static files.

Example:

stoobly-agent mock https://cdn.example.com/data.json --public-directory-path ./public

Q: How do I save mocked response to a file?

A: Use the -o option to write the response to a file.

Example:

stoobly-agent mock https://api.example.com/users -o mock-response.json

---

Connection Strategy

Q: What connection strategies are available?

A: Stoobly supports eager and lazy connection strategies for handling upstream connections.

Example:

# Eager: Connect immediately
stoobly-agent run --connection-strategy eager

# Lazy: Connect only when needed (default)
stoobly-agent run --connection-strategy lazy

---

Complete Examples

Q: How do I set up a complete development environment?

A: Initialize, install CA cert, start agent with intercept mode.

Example:

# Step 1: Initialize
stoobly-agent init

# Step 2: Install CA certificate
stoobly-agent ca-cert install

# Step 3: Start agent with intercept
stoobly-agent run --intercept --intercept-mode record

# Step 4: Configure your app to use proxy
export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080

# Step 5: Make requests (they get recorded)
curl https://api.example.com/users

Q: How do I run Stoobly for API mocking in tests?

A: Start in headless mode with mock mode and fixtures.

Example:

# Start agent
stoobly-agent run \
  --headless \
  --intercept \
  --intercept-mode mock \
  --response-fixtures-path ./test-fixtures.yml \
  --public-directory-path ./test-data

# Run tests
npm test

# Tests use mocked responses

Q: How do I run Stoobly in CI/CD?

A: Use headless, detached mode with specific configuration.

Example:

#!/bin/bash
# CI/CD script

# Start agent in background
stoobly-agent run \
  --headless \
  --intercept \
  --intercept-mode test \
  --detached /tmp/stoobly.log \
  --log-level info

# Get PID
AGENT_PID=$(cat /tmp/stoobly.log | head -1)

# Wait for agent to start
sleep 2

# Run tests
npm test

# Stop agent
kill $AGENT_PID

---

Environment Variables

Q: How do I enable latency simulation for mocked responses?

A: Set the AGENT_SIMULATE_LATENCY environment variable to enable latency simulation. When enabled, Stoobly will simulate the expected response latency based on the X-Stoobly-Response-Latency header value in milliseconds.

Example:

# Enable latency simulation
export AGENT_SIMULATE_LATENCY=1

# Start the agent
stoobly-agent run --intercept --intercept-mode mock

# Mocked responses will now simulate latency based on the X-Stoobly-Response-Latency header

How it works:

• The latency simulation calculates wait time as: expected_latency - estimated_rtt_network_latency - api_latency

• expected_latency comes from the X-Stoobly-Response-Latency response header (in milliseconds)

• estimated_rtt_network_latency is fixed at 15ms

• api_latency is the time elapsed since the request started

• If the calculated wait time is positive, Stoobly will sleep for that duration before returning the response

Use cases:

• Testing how your application handles slow API responses

• Simulating real-world network conditions during development

• Validating timeout and retry logic

Note: This feature only works in mock mode and requires the X-Stoobly-Response-Latency header to be present in the mocked response.

---

Troubleshooting

Q: How do I debug connection issues?

A: Increase log level and flow detail for verbose output.

Example:

stoobly-agent run --log-level debug --flow-detail 4

Q: How do I verify the agent is running?

A: Check the proxy and UI ports.

Example:

# Check proxy
curl -x http://localhost:8080 http://example.com

# Check UI
curl http://localhost:4200

Q: What do I do if ports are already in use?

A: Use custom ports to avoid conflicts.

Example:

# Use different ports
stoobly-agent run --proxy-port 9090 --ui-port 5000

---

Quick Reference

Q: What are the essential commands?

A: Here's a quick reference of the most common commands:

Example:

# Check version
stoobly-agent --version

# Initialize
stoobly-agent init

# Run agent (full)
stoobly-agent run

# Run headless
stoobly-agent run --headless

# Run with intercept
stoobly-agent run --intercept --intercept-mode record

# Run detached
stoobly-agent run --detached /tmp/stoobly.log

# Quick record
stoobly-agent record https://api.example.com/users

# Quick mock
stoobly-agent mock https://api.example.com/users

# Custom ports
stoobly-agent run --proxy-port 9090 --ui-port 5000

# Debug mode
stoobly-agent run --log-level debug --flow-detail 4

# With fixtures
stoobly-agent run --response-fixtures-path ./fixtures.yml

# With lifecycle hooks
stoobly-agent run --lifecycle-hooks-path ./hooks.py