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 "<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 "<PROJECT-KEY>"
# 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 "<PROJECT-KEY>"

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 "<SCENARIO-KEY>"
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 "<API-KEY>"
stoobly-agent config project set "<PROJECT-KEY>"
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 NextInstallation

Last updated 23 days ago

hashtagStoobly Config CLI - Questions & Answers

hashtagUnderstanding Configuration

hashtagQ: What is Stoobly configuration?

hashtagQ: Where is configuration stored?

hashtagViewing and Managing Configuration

hashtagQ: How do I view the current configuration?

hashtagQ: How do I save configuration to a file?

hashtagQ: How do I reset configuration to defaults?

hashtagQ: How do I validate my configuration?

hashtagManaging Active Scenario

hashtagQ: How do I set the active scenario?

hashtagQ: How do I view the currently active scenario?

hashtagQ: How do I clear the active scenario?

hashtagQ: Why would I set an active scenario?

hashtagRewrite Rules

hashtagQ: What are rewrite rules?

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

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

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

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

hashtagQ: How do I rewrite request headers?

hashtagQ: How do I rewrite query parameters?

hashtagQ: How do I rewrite body parameters?

hashtagQ: How do I rewrite response headers?

hashtagQ: How do I rewrite response parameters?

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

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

hashtagMatch Rules

hashtagQ: What are match rules?

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

hashtagQ: How do I match by query parameters?

hashtagQ: How do I match by headers?

hashtagQ: How do I match by body parameters?

hashtagQ: How do I match by multiple components?

hashtagFirewall Rules

hashtagQ: What are firewall rules?

hashtagQ: How do I exclude requests from interception?

hashtagQ: How do I include only specific requests?

hashtagQ: How do I filter by HTTP method?

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

hashtagProject Management (Remote Features)

hashtagQ: How do I set the active project?

hashtagQ: How do I view the current project?

hashtagQ: How do I switch to local project mode?

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

hashtagConfiguration Workflows

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

hashtagQ: How do I configure request filtering for testing?

hashtagQ: How do I mock with modified authentication?

hashtagAdvanced Configuration

hashtagQ: How do I create rules for specific projects?

hashtagQ: How do I configure rules for microservices?

hashtagTroubleshooting

hashtagQ: How do I debug configuration issues?

hashtagQ: How do I reset a specific configuration section?

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

hashtagQuick Reference

hashtagQ: What are the most common config commands?

hashtagBest Practices

hashtagQ: How should I organize my configuration?

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

Stoobly Config CLI - Questions & Answers

Understanding Configuration

Q: What is Stoobly configuration?

Q: Where is configuration stored?

Viewing and Managing Configuration

Q: How do I view the current configuration?

Q: How do I save configuration to a file?

Q: How do I reset configuration to defaults?

Q: How do I validate my configuration?

Managing Active Scenario

Q: How do I set the active scenario?

Q: How do I view the currently active scenario?

Q: How do I clear the active scenario?

Q: Why would I set an active scenario?

Rewrite Rules

Q: What are rewrite rules?

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

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

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

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

Q: How do I rewrite request headers?

Q: How do I rewrite query parameters?

Q: How do I rewrite body parameters?

Q: How do I rewrite response headers?

Q: How do I rewrite response parameters?

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

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

Match Rules

Q: What are match rules?

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

Q: How do I match by query parameters?

Q: How do I match by headers?

Q: How do I match by body parameters?

Q: How do I match by multiple components?

Firewall Rules

Q: What are firewall rules?

Q: How do I exclude requests from interception?

Q: How do I include only specific requests?

Q: How do I filter by HTTP method?

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

Project Management (Remote Features)

Q: How do I set the active project?

Q: How do I view the current project?

Q: How do I switch to local project mode?

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

Configuration Workflows

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

Q: How do I configure request filtering for testing?

Q: How do I mock with modified authentication?

Advanced Configuration

Q: How do I create rules for specific projects?

Q: How do I configure rules for microservices?

Troubleshooting

Q: How do I debug configuration issues?

Q: How do I reset a specific configuration section?

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

Quick Reference

Q: What are the most common config commands?

Best Practices

Q: How should I organize my configuration?

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