# Intercept ## Stoobly Intercept CLI - Questions & Answers The intercept CLI allows you to dynamically configure the stoobly-agent **after** it's already running with `stoobly-agent run`. This enables you to change modes, policies, and strategies without restarting the agent. *** ### Getting Started with Intercept #### Q: What is the intercept feature? **A:** Intercept is a feature that allows the stoobly-agent proxy to capture, modify, and control HTTP requests in real-time. You can enable/disable it and configure its behavior while the agent is running. **Example:** ```bash # Start the agent stoobly-agent run # In another terminal, enable intercept stoobly-agent intercept enable ``` #### Q: How do I check the current intercept configuration? **A:** Use the `intercept show` command to display the current mode, policy, strategy, and status. **Example:** ```bash stoobly-agent intercept show # Output: Mock with policy: 'found', strategy: 'None', enabled ``` *** ### Enabling and Disabling Intercept #### Q: How do I enable intercept mode? **A:** Use `stoobly-agent intercept enable` to activate request interception on a running agent. **Example:** ```bash # Start agent first stoobly-agent run # In another terminal, enable intercept stoobly-agent intercept enable # Output: Intercept enabled! ``` #### Q: How do I disable intercept mode? **A:** Use `stoobly-agent intercept disable` to deactivate request interception without stopping the agent. **Example:** ```bash stoobly-agent intercept disable # Output: Intercept disabled! ``` #### Q: Can I enable intercept when starting the agent? **A:** Yes, use the `--intercept` flag when running the agent to enable it at startup. **Example:** ```bash stoobly-agent run --intercept --intercept-mode mock ``` *** ### Configuring Intercept Modes #### Q: What intercept modes are available? **A:** There are four intercept modes: `mock`, `record`, `replay`, and `test` (test requires remote features enabled). **Example:** ```bash # View available modes stoobly-agent intercept set --help # Set to mock mode stoobly-agent intercept set --mode mock # Set to record mode stoobly-agent intercept set --mode record # Set to replay mode stoobly-agent intercept set --mode replay # Set to test mode (if remote features enabled) stoobly-agent intercept set --mode test ``` #### Q: How do I switch from record mode to mock mode? **A:** Use the `intercept configure --mode` command to change modes while the agent is running. **Example:** ```bash # Currently in record mode, switch to mock stoobly-agent intercept set --mode mock # Output: Updating intercept mode to mock ``` #### Q: What happens when I change the intercept mode? **A:** When you change modes, intercept is automatically disabled, the mode is updated, and you need to re-enable intercept for the new mode to take effect. **Example:** ```bash # Change mode (intercept gets disabled) stoobly-agent intercept set --mode record # Re-enable intercept stoobly-agent intercept enable ``` *** ### Mock Mode Configuration #### Q: What is mock mode? **A:** Mock mode serves previously recorded responses instead of making real HTTP requests, useful for testing without external dependencies. **Example:** ```bash stoobly-agent intercept set --mode mock stoobly-agent intercept enable ``` #### Q: What policies are available for mock mode? **A:** Mock mode supports two policies: `all` (mock all requests) and `found` (only mock requests with recorded responses). **Example:** ```bash # Mock all requests stoobly-agent intercept set --mode mock --policy all # Only mock requests that have recorded responses stoobly-agent intercept set --mode mock --policy found ``` #### Q: How do I configure mock mode to only serve recorded responses? **A:** Set the mock policy to `found` to only mock requests that have matching recorded responses. **Example:** ```bash stoobly-agent intercept set --mode mock --policy found stoobly-agent intercept enable ``` *** ### Record Mode Configuration #### Q: What is record mode? **A:** Record mode captures HTTP requests and responses as they pass through the proxy, storing them for later replay or mocking. **Example:** ```bash stoobly-agent intercept set --mode record stoobly-agent intercept enable ``` #### Q: What policies are available for record mode? **A:** Record mode supports four policies: `all`, `api`, `found`, and `not_found`. **Example:** ```bash # Record all requests stoobly-agent intercept set --mode record --policy all # Record only API requests stoobly-agent intercept set --mode record --policy api # Record only requests with existing records stoobly-agent intercept set --mode record --policy found # Record only new requests (not previously recorded) stoobly-agent intercept set --mode record --policy not_found ``` #### Q: What recording strategies are available? **A:** Record mode supports two strategies: `full` (capture complete request/response) and `minimal` (capture only essential data). **Example:** ```bash # Full recording (complete data) stoobly-agent intercept set --mode record --strategy full # Minimal recording (essential data only) stoobly-agent intercept set --mode record --strategy minimal ``` #### Q: What recording orders are available? **A:** Record mode supports two orders: `append` (add new records) and `overwrite` (replace existing records). **Example:** ```bash # Append new recordings stoobly-agent intercept set --mode record --order append # Overwrite existing recordings stoobly-agent intercept set --mode record --order overwrite ``` #### Q: How do I configure record mode to only capture new requests? **A:** Set the record policy to `not_found` to only record requests that haven't been captured before. **Example:** ```bash stoobly-agent intercept set --mode record --policy not_found stoobly-agent intercept enable ``` #### Q: How do I configure record mode to overwrite existing recordings? **A:** Set the record order to `overwrite` to replace existing recordings with new captures. **Example:** ```bash stoobly-agent intercept set --mode record --order overwrite stoobly-agent intercept enable ``` *** ### Replay Mode Configuration #### Q: What is replay mode? **A:** Replay mode re-executes previously recorded requests, useful for testing and debugging. **Example:** ```bash stoobly-agent intercept set --mode replay stoobly-agent intercept enable ``` #### Q: What policies are available for replay mode? **A:** Replay mode currently supports the `all` policy to replay all intercepted requests. **Example:** ```bash stoobly-agent intercept set --mode replay --policy all stoobly-agent intercept enable ``` *** ### Test Mode Configuration #### Q: What is test mode? **A:** Test mode validates responses against expected results, useful for automated testing and contract validation. **Example:** ```bash stoobly-agent intercept set --mode test stoobly-agent intercept enable ``` #### Q: What policies are available for test mode? **A:** Test mode supports the `found` policy to only test requests with recorded responses. **Example:** ```bash stoobly-agent intercept set --mode test --policy found stoobly-agent intercept enable ``` #### Q: What test strategies are available? **A:** Test mode supports four strategies: `contract`, `custom`, `diff`, and `fuzzy`. **Example:** ```bash # Contract testing (validate against schema) stoobly-agent intercept set --mode test --strategy contract # Custom testing (use custom validation logic) stoobly-agent intercept set --mode test --strategy custom # Diff testing (compare exact responses) stoobly-agent intercept set --mode test --strategy diff # Fuzzy testing (allow minor variations) stoobly-agent intercept set --mode test --strategy fuzzy ``` #### Q: How do I set up contract testing? **A:** Configure test mode with the contract strategy to validate responses against defined schemas. **Example:** ```bash stoobly-agent intercept set --mode test --strategy contract --policy found stoobly-agent intercept enable ``` *** ### Advanced Configuration #### Q: Can I configure multiple options at once? **A:** Yes, you can combine mode, policy, strategy, and order options in a single command. **Example:** ```bash # Configure record mode with all options stoobly-agent intercept set --mode record --policy not_found --strategy full --order append # Configure test mode with strategy and policy stoobly-agent intercept set --mode test --strategy diff --policy found ``` #### Q: How do I configure intercept for a specific scenario? **A:** First configure the mode and settings, then enable intercept. Use lifecycle hooks for scenario-specific logic. **Example:** ```bash # Configure for recording a specific API stoobly-agent intercept set --mode record --policy api --strategy full stoobly-agent intercept enable # Run your tests/requests # ... # Switch to mock mode for testing stoobly-agent intercept set --mode mock --policy found stoobly-agent intercept enable ``` *** ### Workflow Examples #### Q: How do I set up a record-then-mock workflow? **A:** Start by recording requests, then switch to mock mode to replay them. Optionally create a scenario before recording to organize your requests. **Example:** ```bash # Step 1: Start the agent stoobly-agent run # Step 2 (Optional): Create a scenario to organize requests stoobly-agent scenario create "My User Flow" # Output: Created scenario with key: # Step 3: Configure and enable recording stoobly-agent intercept set --mode record --policy all --strategy full stoobly-agent intercept enable # Step 4: Make requests (they get recorded) # ... perform your API calls ... # Step 5: Switch to mock mode stoobly-agent intercept set --mode mock --policy found stoobly-agent intercept enable # Step 6: Run tests against mocked responses # ... run your test suite ... ``` #### Q: How do I set up continuous recording with overwrite? **A:** Configure record mode with overwrite order to always capture the latest responses. **Example:** ```bash stoobly-agent run --intercept --intercept-mode record # In another terminal stoobly-agent intercept set --mode record --order overwrite --policy all ``` #### Q: How do I set up automated testing with validation? **A:** Configure test mode with your preferred validation strategy. **Example:** ```bash # Start agent stoobly-agent run # Configure test mode with diff strategy stoobly-agent intercept set --mode test --strategy diff --policy found stoobly-agent intercept enable # Run your test suite - responses will be validated automatically ``` *** ### Troubleshooting #### Q: What happens if I try to set an invalid policy for a mode? **A:** The command will fail with an error message showing valid policies for that mode. **Example:** ```bash # This will fail if policy is invalid for the mode stoobly-agent intercept set --mode mock --policy not_found # Output: Error: Valid policies for mock are ['all', 'found'] ``` #### Q: Why does intercept get disabled when I change modes? **A:** Changing modes requires reconfiguring the proxy behavior, so intercept is automatically disabled. You need to re-enable it after changing modes. **Example:** ```bash # Change mode (intercept disabled automatically) stoobly-agent intercept set --mode record # Check status stoobly-agent intercept show # Output: Record with policy: 'all', strategy: 'full', disabled # Re-enable intercept stoobly-agent intercept enable ``` #### Q: How do I verify my intercept configuration is working? **A:** Use `intercept show` to check the current configuration and status. **Example:** ```bash stoobly-agent intercept show # Output: Mock with policy: 'found', strategy: 'None', enabled ``` **Technique 2 — Inspect response headers with curl:** Stoobly injects `x-stoobly-*` headers into responses it serves. Re-run your request with `-v` (verbose) to see them: ```bash curl -v --proxy http://localhost:8080 https://your-api.example.com/path ``` Look for a header like `x-stoobly-mock: 1` in the response. If it's present, the response came from Stoobly — not the real service. This is the quickest way to confirm end-to-end that the proxy is intercepting and serving your request. **Technique 3 — Edit a recorded response (most definitive):** Open the Stoobly UI at `http://localhost:4200`, find the recorded request, edit its response body to something obviously fake, then re-run your curl. If you receive the fake value, Stoobly owns the response. #### Q: Can I configure intercept before enabling it? **A:** Yes, you can configure all settings first, then enable intercept to apply them. **Example:** ```bash # Configure first stoobly-agent intercept set --mode record --policy all --strategy full --order append # Then enable stoobly-agent intercept enable ``` *** ### Quick Reference #### Q: What's a quick reference for common intercept commands? **A:** Here are the most frequently used intercept commands: **Example:** ```bash # View current configuration stoobly-agent intercept show # Enable/disable intercept stoobly-agent intercept enable stoobly-agent intercept disable # Switch modes stoobly-agent intercept set --mode mock stoobly-agent intercept set --mode record stoobly-agent intercept set --mode replay stoobly-agent intercept set --mode test # Configure record mode stoobly-agent intercept set --mode record --policy all --strategy full --order append # Configure mock mode stoobly-agent intercept set --mode mock --policy found # Configure test mode stoobly-agent intercept set --mode test --strategy diff --policy found # Complete workflow stoobly-agent intercept set --mode record --policy all stoobly-agent intercept enable # ... make requests ... stoobly-agent intercept set --mode mock --policy found stoobly-agent intercept enable # ... run tests ... ``` *** ### Integration with Other Features #### Q: How does intercept work with scenarios? **A:** Intercept can be configured to work with specific scenarios for organized request management. **Example:** ```bash # Record requests to a scenario stoobly-agent run --intercept --intercept-mode record --scenario-key "" # Configure intercept for the scenario stoobly-agent intercept set --mode record --policy all ``` #### Q: Can I use intercept with lifecycle hooks? **A:** Yes, intercept works seamlessly with lifecycle hooks for custom request/response processing. **Example:** ```bash # Start with lifecycle hooks stoobly-agent run --lifecycle-hooks-path ./hooks.py # Configure intercept stoobly-agent intercept set --mode mock --policy found stoobly-agent intercept enable ``` ``` This comprehensive Q&A guide covers all aspects of the intercept CLI, providing users with clear examples for configuring and managing request interception dynamically while the agent is running. ``` --- # 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/intercept.md?ask= ``` 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.