Config

Stoobly Config CLI - Questions & Answers

The config CLI manages Stoobly configuration including proxy settings, scenarios, rewrite rules, match rules, firewall rules, and project settings. It allows runtime configuration of the agent without editing files directly.

Understanding Configuration

Q: What is Stoobly configuration?

A: Configuration controls how Stoobly intercepts, modifies, and routes HTTP requests. It includes rewrite rules for transforming requests, match rules for identifying requests, and firewall rules for filtering traffic.

Example:

# View current configuration
stoobly-agent config dump

# View configuration directory
stoobly-agent config dump --dir

Q: Where is configuration stored?

A: Configuration is stored in the .stoobly directory, typically in ~/.stoobly/settings.yml or your project's .stoobly/settings.yml.

Example:

# View config directory location
stoobly-agent config dump --dir
# Output: /home/user/.stoobly

# View full configuration
stoobly-agent config dump

Viewing and Managing Configuration

Q: How do I view the current configuration?

A: Use config dump to display all configuration settings.

Example:

# Display configuration as JSON
stoobly-agent config dump

Q: How do I save configuration to a file?

A: Use the --save-to-file flag to export configuration.

Example:

# Save to timestamped file
stoobly-agent config dump --save-to-file
# Output: Config successfully dumped to stoobly_agent_config_dump_1234567890.json

# View the file
cat stoobly_agent_config_dump_*.json

Q: How do I reset configuration to defaults?

A: Use config reset to restore default settings.

Example:

stoobly-agent config reset
# Output: Reset /home/user/.stoobly/settings.yml to defaults.

Q: How do I validate my configuration?

A: Use config validate to check for configuration errors.

Example:

stoobly-agent config validate

Managing Active Scenario

Q: How do I set the active scenario?

A: Use config scenario set with the scenario key to make it active for intercept operations.

Example:

stoobly-agent config scenario set abc123-scenario-key
# Output: Scenario updated!

Q: How do I view the currently active scenario?

A: Use config scenario show to display active scenario details.

Example:

stoobly-agent config scenario show

Q: How do I clear the active scenario?

A: Use config scenario clear to remove the active scenario setting.

Example:

stoobly-agent config scenario clear
# Output: Scenario cleared!

Q: Why would I set an active scenario?

A: Setting an active scenario directs all intercepted requests to that scenario automatically, useful for organizing recorded requests during development.

Example:

# Set active scenario
stoobly-agent config scenario set user-login-flow

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

# All recorded requests go to user-login-flow scenario

Rewrite Rules

Q: What are rewrite rules?

A: Rewrite rules transform HTTP requests in flight, allowing you to modify URLs, headers, query parameters, or body parameters before they're sent or matched.

Example:

# Rewrite host from old to new
stoobly-agent config rewrite set \
  --pattern "https://old-api.example.com/.*" \
  --method GET \
  --method POST \
  --mode mock \
  --mode record \
  --hostname new-api.example.com

Q: How do I create a rewrite rule to change the hostname?

A: Use config rewrite set with --hostname option.

Example:

stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --method POST \
  --mode mock \
  --hostname api-staging.example.com

Q: How do I create a rewrite rule to change the URL path?

A: Use the --path option to specify the new path.

Example:

# Rewrite /v1/users to /v2/users
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/v1/users" \
  --method GET \
  --mode mock \
  --mode record \
  --path "/v2/users"

Q: How do I create a rewrite rule to change the scheme?

A: Use the --scheme option to switch between http and https.

Example:

# Change https to http
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --mode mock \
  --scheme http

Q: How do I create a rewrite rule to change the port?

A: Use the --port option to specify a different port.

Example:

# Redirect to different port
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --mode mock \
  --port 8443

Q: How do I rewrite request headers?

A: Use --type header with --name and --value options.

Example:

# Add/modify Authorization header
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --method POST \
  --mode mock \
  --mode record \
  --type header \
  --name "Authorization" \
  --value "Bearer new-token"

Q: How do I rewrite query parameters?

A: Use --type query_param with parameter name and value.

Example:

# Rewrite api_key query parameter
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --mode mock \
  --type query_param \
  --name "api_key" \
  --value "test-key-123"

Q: How do I rewrite body parameters?

A: Use --type body_param for POST/PUT request body parameters.

Example:

# Rewrite userId in request body
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/users" \
  --method POST \
  --mode record \
  --type body_param \
  --name "userId" \
  --value "test-user-123"

Q: How do I rewrite response headers?

A: Use --type response_header to modify response headers.

Example:

# Add custom response header
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --mode mock \
  --type response_header \
  --name "X-Custom-Header" \
  --value "custom-value"

Q: How do I rewrite response parameters?

A: Use --type response_param to modify response body parameters.

Example:

# Rewrite response data
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --mode mock \
  --type response_param \
  --name "status" \
  --value "success"

Q: How do I apply rewrite rules to specific modes?

A: Use multiple --mode options to specify which intercept modes the rule applies to.

Example:

# Apply only to mock and test modes
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --mode mock \
  --mode test \
  --hostname localhost:8080

Q: How do I create rewrite rules for specific HTTP methods?

A: Use multiple --method options to target specific methods.

Example:

# Apply to GET and POST only
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --method POST \
  --mode mock \
  --hostname api-mock.local

Match Rules

Q: What are match rules?

A: Match rules determine which request components (headers, query params, body params) are used to match requests to recorded responses during mocking or testing.

Example:

# Match by query parameters and headers
stoobly-agent config match set \
  --pattern "https://api.example.com/users" \
  --method GET \
  --mode mock \
  --component query_param \
  --component header

Q: How do I create a match rule to ignore certain components?

A: Specify only the components you want to match; unspecified components are ignored.

Example:

# Match only by path, ignore query params
stoobly-agent config match set \
  --pattern "https://api.example.com/search" \
  --method GET \
  --mode mock
  # No --component means match by path/method only

Q: How do I match by query parameters?

A: Use --component query_param to include query parameters in matching.

Example:

stoobly-agent config match set \
  --pattern "https://api.example.com/search" \
  --method GET \
  --mode mock \
  --component query_param

Q: How do I match by headers?

A: Use --component header to include headers in matching.

Example:

# Match by Authorization header
stoobly-agent config match set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --method POST \
  --mode mock \
  --component header

Q: How do I match by body parameters?

A: Use --component body_param for POST/PUT request body matching.

Example:

stoobly-agent config match set \
  --pattern "https://api.example.com/users" \
  --method POST \
  --mode mock \
  --component body_param

Q: How do I match by multiple components?

A: Use multiple --component options to combine matching criteria.

Example:

# Match by query params AND headers
stoobly-agent config match set \
  --pattern "https://api.example.com/search" \
  --method GET \
  --mode mock \
  --component query_param \
  --component header

Firewall Rules

Q: What are firewall rules?

A: Firewall rules filter which requests are intercepted, allowing you to include or exclude specific URLs, methods, or patterns.

Example:

# Exclude analytics requests from recording
stoobly-agent config firewall set \
  --pattern "https://analytics.example.com/.*" \
  --method GET \
  --method POST \
  --mode record \
  --action exclude

Q: How do I exclude requests from interception?

A: Use --action exclude with a pattern to filter out requests.

Example:

# Exclude third-party tracking
stoobly-agent config firewall set \
  --pattern "https://.*google-analytics.com/.*" \
  --method GET \
  --method POST \
  --mode record \
  --mode mock \
  --action exclude

Q: How do I include only specific requests?

A: Use --action include with a pattern to whitelist requests.

Example:

# Only intercept API requests
stoobly-agent config firewall set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --method POST \
  --mode record \
  --action include

Q: How do I filter by HTTP method?

A: Use multiple --method options to target specific methods.

Example:

# Exclude OPTIONS requests
stoobly-agent config firewall set \
  --pattern ".*" \
  --method OPTIONS \
  --mode record \
  --mode mock \
  --action exclude

Q: How do I apply firewall rules to specific modes?

A: Use multiple --mode options to control which intercept modes are affected.

Example:

# Exclude from recording only, still mock
stoobly-agent config firewall set \
  --pattern "https://cdn.example.com/.*" \
  --method GET \
  --mode record \
  --action exclude

Project Management (Remote Features)

Q: How do I set the active project?

A: Use config project set with the project key (requires remote features).

Example:

stoobly-agent config project set proj-abc123
# Output: Project updated!

Q: How do I view the current project?

A: Use config project show to display active project details.

Example:

stoobly-agent config project show

Q: How do I switch to local project mode?

A: Use config project local to use local storage instead of remote.

Example:

stoobly-agent config project local
# Output: Using local project!

Q: How do I set my API key for remote features?

A: Use config api-key set with your API key.

Example:

stoobly-agent config api-key set your-api-key-here
# Output: API Key updated!

Configuration Workflows

Q: How do I set up environment-specific rewrite rules?

A: Create rewrite rules that redirect production URLs to local or staging environments.

Example:

# Development: Point to localhost
stoobly-agent config rewrite set \
  --pattern "https://api.production.com/.*" \
  --method GET \
  --method POST \
  --mode mock \
  --mode test \
  --hostname localhost:8080 \
  --scheme http

# Staging: Point to staging server
stoobly-agent config rewrite set \
  --pattern "https://api.production.com/.*" \
  --method GET \
  --method POST \
  --mode record \
  --hostname api.staging.com

Q: How do I configure request filtering for testing?

A: Combine firewall and match rules to control which requests are tested.

Example:

# Exclude external services from tests
stoobly-agent config firewall set \
  --pattern "https://.*amazonaws.com/.*" \
  --method GET \
  --method POST \
  --mode test \
  --action exclude

# Match API requests precisely
stoobly-agent config match set \
  --pattern "https://api.myapp.com/.*" \
  --method GET \
  --method POST \
  --mode test \
  --component query_param \
  --component header

Q: How do I mock with modified authentication?

A: Use rewrite rules to replace authentication tokens in mock mode.

Example:

# Replace auth tokens for mocking
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --method POST \
  --mode mock \
  --type header \
  --name "Authorization" \
  --value "Bearer test-token"

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

Advanced Configuration

Q: How do I create rules for specific projects?

A: Use the --project-key option to scope rules to a specific project.

Example:

# Add rewrite rule to specific project
stoobly-agent config rewrite set \
  --pattern "https://api.example.com/.*" \
  --method GET \
  --mode mock \
  --hostname localhost \
  --project-key proj-abc123

Q: How do I configure rules for microservices?

A: Create separate rules for each service endpoint.

Example:

# Auth service
stoobly-agent config rewrite set \
  --pattern "https://auth.example.com/.*" \
  --method GET \
  --method POST \
  --mode mock \
  --hostname localhost:8001

# User service
stoobly-agent config rewrite set \
  --pattern "https://users.example.com/.*" \
  --method GET \
  --method POST \
  --mode mock \
  --hostname localhost:8002

# Order service
stoobly-agent config rewrite set \
  --pattern "https://orders.example.com/.*" \
  --method GET \
  --method POST \
  --mode mock \
  --hostname localhost:8003

Troubleshooting

Q: How do I debug configuration issues?

A: Dump configuration and validate it.

Example:

# View configuration
stoobly-agent config dump

# Validate configuration
stoobly-agent config validate

# Check for specific rules
stoobly-agent config dump | jq '.proxy.rewrite'
stoobly-agent config dump | jq '.proxy.firewall'
stoobly-agent config dump | jq '.proxy.match'

Q: How do I reset a specific configuration section?

A: Currently, you can only reset all configuration. To reset specific sections, edit the config file manually or use reset and reconfigure.

Example:

# Backup current config
stoobly-agent config dump --save-to-file

# Reset to defaults
stoobly-agent config reset

# Reconfigure specific sections
stoobly-agent config rewrite set ...

Q: How do I check if my rewrite rules are working?

A: Use increased logging and flow detail to see rule application.

Example:

# Start with debug logging
stoobly-agent run --log-level debug --flow-detail 4 --intercept --intercept-mode mock

# Make request and check logs for rewrite application

Quick Reference

Q: What are the most common config commands?

A: Here's a quick reference of frequently used commands:

Example:

# View configuration
stoobly-agent config dump
stoobly-agent config dump --dir
stoobly-agent config dump --save-to-file

# Reset configuration
stoobly-agent config reset
stoobly-agent config validate

# Manage scenarios
stoobly-agent config scenario set abc123
stoobly-agent config scenario show
stoobly-agent config scenario clear

# Rewrite rules
stoobly-agent config rewrite set \
  --pattern "URL_PATTERN" \
  --method GET --method POST \
  --mode mock --mode record \
  --hostname new-host.com

# Match rules
stoobly-agent config match set \
  --pattern "URL_PATTERN" \
  --method GET \
  --mode mock \
  --component query_param --component header

# Firewall rules
stoobly-agent config firewall set \
  --pattern "URL_PATTERN" \
  --method GET \
  --mode record \
  --action exclude

# Project management (remote features)
stoobly-agent config api-key set YOUR_API_KEY
stoobly-agent config project set proj-abc123
stoobly-agent config project show
stoobly-agent config project local

Best Practices

Q: How should I organize my configuration?

A: Use specific patterns for different services and environments.

Example:

# Service-specific patterns
stoobly-agent config rewrite set --pattern "https://api.myapp.com/.*" ...
stoobly-agent config rewrite set --pattern "https://auth.myapp.com/.*" ...

# Environment-specific rules
stoobly-agent config rewrite set --mode mock --hostname localhost ...
stoobly-agent config rewrite set --mode record --hostname staging.com ...

Q: When should I use firewall rules vs match rules?

A: Use firewall rules to filter what gets intercepted, match rules to control how requests are matched to responses.

Example:

# Firewall: Exclude from interception
stoobly-agent config firewall set --pattern "https://cdn..*" --action exclude

# Match: Control matching precision
stoobly-agent config match set --pattern "https://api..*" --component query_param

PreviousCA Cert NextIntercept

Last updated 11 days ago

Was this helpful?