# 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:**

```bash
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:**

```bash
# 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:**

```bash
# 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:**

```bash
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:**

```bash
# 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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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 logs list command while the agent is running or after. Use `-f` to stream logs in real time, or filter by method, URL, status code, and more.

**Examples:**

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

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

# Follow logs in real time (-f / --follow, Ctrl-C to stop)
stoobly-agent request logs list --follow

# Filter by log level
stoobly-agent request logs list --level error

# Filter by URL and method
stoobly-agent request logs list --url /api --method post
```

***

### 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:**

```bash
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:**

```bash
# 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:**

```bash
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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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-dir-path` option to serve files from a directory.

**Example:**

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

# Run with public directory
stoobly-agent run --public-dir-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:**

```bash
stoobly-agent run \
  --response-fixtures-path "./fixtures.yml:https://api.example.com" \
  --public-dir-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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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:**

```bash
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:**

```bash
# 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:**

```bash
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:**

```bash
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:**

```bash
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-dir-path` option to serve static files.

**Example:**

```bash
stoobly-agent mock https://cdn.example.com/data.json --public-dir-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:**

```bash
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:**

```bash
# 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, optionally create a scenario, then start agent with intercept mode.

**Example:**

```bash
# Step 1: Initialize
stoobly-agent init

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

# Step 3 (Optional): Create a scenario to organize requests
stoobly-agent scenario create "My User Flow"
# Output: Created scenario with key: <SCENARIO-KEY>

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

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

# Step 6: 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:**

```bash
# Start agent
stoobly-agent run \
  --headless \
  --intercept \
  --intercept-mode mock \
  --response-fixtures-path ./test-fixtures.yml \
  --public-dir-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:**

```bash
#!/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:**

```bash
# 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:**

```bash
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:**

```bash
# 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:**

```bash
# 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:**

```bash
# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stoobly.com/faq/run.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.