Request

Stoobly Request CLI - Questions & Answers

The request CLI enables you to manage recorded HTTP requests, replay them, test responses, and work with request/response data. These commands help you work with individual requests outside of scenarios.

Listing Requests

Q: How do I view all recorded requests?

A: Use request list to display all recorded requests with pagination.

Example:

stoobly-agent request list

Q: How do I paginate through requests?

A: Use the --page and --size options to control pagination.

Example:

# Show first 10 requests (default)
stoobly-agent request list --page 0 --size 10

# Show next 20 requests
stoobly-agent request list --page 1 --size 20

# Show 50 requests per page
stoobly-agent request list --page 0 --size 50

Q: How do I filter requests by scenario?

A: Use the --scenario-key option to show only requests from a specific scenario.

Example:

stoobly-agent request list --scenario-key abc123-scenario-key

Q: How do I search for specific requests?

A: Use the --search option to filter requests by URL path or other criteria.

Example:

# Search by path
stoobly-agent request list --search "/api/users"

# Search by domain
stoobly-agent request list --search "example.com"

Q: How do I sort requests?

A: Use --sort-by and --sort-order options to control sorting.

Example:

# Sort by creation date (newest first, default)
stoobly-agent request list --sort-by created_at --sort-order desc

# Sort by creation date (oldest first)
stoobly-agent request list --sort-by created_at --sort-order asc

# Sort by path
stoobly-agent request list --sort-by path --sort-order asc

Q: How do I format the request list output?

A: Use the --format option to change output format (table, json, csv).

Example:

# Table format (default)
stoobly-agent request list --format table

# JSON format
stoobly-agent request list --format json

# CSV format
stoobly-agent request list --format csv

Q: How do I select specific columns to display?

A: Use the --select option to choose which columns to show.

Example:

# Show only specific columns
stoobly-agent request list --select id --select path --select method

# Show multiple columns
stoobly-agent request list --select id --select path --select method --select created_at

Q: How do I hide column headers?

A: Use the --without-headers flag to disable column headers.

Example:

stoobly-agent request list --without-headers

Q: How do I export requests to a file?

A: Use format options and shell redirection to export requests.

Example:

# Export as JSON
stoobly-agent request list --format json > requests.json

# Export as CSV
stoobly-agent request list --format csv > requests.csv

# Export specific scenario
stoobly-agent request list --scenario-key abc123 --format json > scenario-requests.json

Replaying Requests

Q: How do I replay a recorded request?

A: Use request replay with the request key to re-execute a recorded request.

Example:

stoobly-agent request replay xyz789-request-key

Q: How do I replay a request to a different host?

A: Use the --host option to override the request host.

Example:

# Replay to localhost
stoobly-agent request replay xyz789 --host localhost:8080

# Replay to staging
stoobly-agent request replay xyz789 --host staging.example.com

Q: How do I replay a request with a different scheme (HTTP/HTTPS)?

A: Use the --scheme option to change the protocol.

Example:

# Force HTTP
stoobly-agent request replay xyz789 --scheme http

# Force HTTPS
stoobly-agent request replay xyz789 --scheme https

Q: How do I replay a request and record the new response?

A: Use the --record flag to capture the replayed response.

Example:

stoobly-agent request replay xyz789 --record

Q: How do I replay a request and overwrite the existing response?

A: Use the --overwrite flag to replace the stored response (local mode only).

Example:

stoobly-agent request replay xyz789 --overwrite

Q: How do I replay a request to a specific scenario?

A: Use the --scenario-key option to record the replay into a scenario.

Example:

stoobly-agent request replay xyz789 --record --scenario-key abc123

Q: How do I format the replay response output?

A: Use the --format option to control response display.

Example:

# Body only
stoobly-agent request replay xyz789 --format body

# Full JSON with metadata
stoobly-agent request replay xyz789 --format json

Q: How do I replay a request with custom lifecycle hooks?

A: Use the --lifecycle-hooks-path option to apply custom processing.

Example:

stoobly-agent request replay xyz789 --lifecycle-hooks-path ./hooks.py

Q: How do I increase logging verbosity when replaying?

A: Use the --log-level option to see more details.

Example:

# Debug level (most verbose)
stoobly-agent request replay xyz789 --log-level debug

# Info level
stoobly-agent request replay xyz789 --log-level info

Working with Aliases (Remote Features)

Q: How do I replay a request with assigned alias values?

A: Use the --assign option to set alias values before replay.

Example:

# Assign single alias
stoobly-agent request replay xyz789 --assign userId=12345

# Assign multiple aliases
stoobly-agent request replay xyz789 --assign userId=12345 --assign token=abc123

Q: How do I validate alias values during replay?

A: Use the --validate option to specify validation rules for aliases.

Example:

# Validate userId is an integer
stoobly-agent request replay xyz789 --validate "userId=?int"

# Validate multiple aliases
stoobly-agent request replay xyz789 --validate "userId=?int" --validate "email=?string"

Q: How do I control alias resolution strategy?

A: Use the --alias-resolve-strategy option to specify how aliases are resolved.

Example:

# No alias resolution (default)
stoobly-agent request replay xyz789 --alias-resolve-strategy none

# First-in-first-out resolution
stoobly-agent request replay xyz789 --alias-resolve-strategy fifo

# Last-in-first-out resolution
stoobly-agent request replay xyz789 --alias-resolve-strategy lifo

Q: How do I repeat a request replay for each alias value?

A: Use the --group-by option to iterate over alias values.

Example:

# Replay once for each userId value
stoobly-agent request replay xyz789 --group-by userId

# Results in multiple replays with different userId values

Q: How do I use an existing trace for replay?

A: Use the --trace-id option to leverage a previous trace.

Example:

stoobly-agent request replay xyz789 --trace-id trace-abc123

Snapshots and Version Control

Q: How do I create a snapshot of a request?

A: Use request snapshot to create a committable file for the request (local mode only).

Example:

stoobly-agent request snapshot xyz789-request-key

Q: How do I delete a request snapshot?

A: Use the --action delete option with snapshot command.

Example:

stoobly-agent request snapshot xyz789 --action delete

Q: How do I snapshot a request with decoded response body?

A: Use the --decode flag to decode the response body in the snapshot.

Example:

stoobly-agent request snapshot xyz789 --decode

Q: How do I reset a request to its snapshot state?

A: Use request reset to restore a request from its snapshot.

Example:

stoobly-agent request reset xyz789-request-key

Q: How do I force delete when resetting a request?

A: Use the --force flag to hard delete the request data.

Example:

stoobly-agent request reset xyz789 --force

Q: How do I share requests with my team via git?

A: Create snapshots and commit them to version control.

Example:

# Create snapshot
stoobly-agent request snapshot xyz789

# Commit to git
git add .stoobly/snapshots/
git commit -m "Add request snapshot"
git push

# Team member pulls and uses
git pull
stoobly-agent request reset xyz789  # Restore from snapshot
stoobly-agent request replay xyz789  # Use the request

Managing Request Responses

Q: How do I view the response for a recorded request?

A: Use request response get to retrieve the stored response.

Example:

stoobly-agent request response get xyz789-request-key

Q: How do I query specific properties in a response?

A: Use request response query with a query expression.

Example:

# Query JSON path
stoobly-agent request response query xyz789 --query "$.data.users[0].name"

# Query nested property
stoobly-agent request response query xyz789 --query "$.response.body"

Q: How do I extract data from a response for scripting?

A: Combine response query with shell processing.

Example:

# Extract user ID
userId=$(stoobly-agent request response query xyz789 --query "$.data.id")

# Use in another command
echo "User ID: $userId"

# Extract array of values
stoobly-agent request response query xyz789 --query "$.data.users[*].email"

Deleting Requests

Q: How do I delete a recorded request?

A: Use request delete with the request key.

Example:

stoobly-agent request delete xyz789-request-key

Q: How do I delete multiple requests?

A: Use a loop or script to delete requests in bulk.

Example:

# Delete multiple specific requests
stoobly-agent request delete xyz789
stoobly-agent request delete abc123
stoobly-agent request delete def456

# Delete all requests from a scenario (scripted)
for key in $(stoobly-agent request list --scenario-key abc123 --format json | jq -r '.[].id'); do
  stoobly-agent request delete $key
done

Managing Intercepted Request Logs

Q: How do I view the intercepted requests log?

A: Use request log list to display all logged intercepted requests.

Example:

stoobly-agent request log list

Q: How do I clear the intercepted requests log?

A: Use request log delete to truncate the log file.

Example:

stoobly-agent request log delete

Q: How do I enable request logging?

A: Use the --request-log-enable flag when starting the agent.

Example:

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

# View logs in another terminal
stoobly-agent request log list

Q: How do I set the log level for intercepted requests?

A: Use the --request-log-level option when starting the agent.

Example:

stoobly-agent run --request-log-enable --request-log-level debug

Q: How do I prevent log truncation on startup?

A: Set --request-log-truncate to false when starting the agent.

Example:

# Don't truncate log on startup
stoobly-agent run --request-log-enable --request-log-truncate=false

Advanced Request Operations

Q: How do I replay multiple requests in sequence?

A: Use a loop or script to replay requests sequentially.

Example:

# Replay multiple requests
for key in xyz789 abc123 def456; do
  stoobly-agent request replay $key
done

# Replay all requests in a scenario
for key in $(stoobly-agent request list --scenario-key abc123 --format json | jq -r '.[].id'); do
  stoobly-agent request replay $key --record
done

Q: How do I compare requests before and after changes?

A: Replay and record, then use snapshots to track changes.

Example:

# Create initial snapshot
stoobly-agent request snapshot xyz789

# Make changes and replay
stoobly-agent request replay xyz789 --overwrite

# Compare with snapshot
git diff .stoobly/snapshots/requests/xyz789.json

Q: How do I chain requests with dependencies?

A: Use aliases and assign values from one request to another.

Example:

# First request creates a user, extract ID
userId=$(stoobly-agent request response query create-user-req --query "$.data.id")

# Second request uses that ID
stoobly-agent request replay get-user-req --assign "userId=$userId"

Q: How do I replay a request with custom headers?

A: Use lifecycle hooks to modify request headers before replay.

Example:

# Create hooks.py with custom header logic
cat > hooks.py << 'EOF'
def before_request(context):
    context.request.headers['X-Custom-Header'] = 'custom-value'
    return context
EOF

# Replay with hooks
stoobly-agent request replay xyz789 --lifecycle-hooks-path ./hooks.py

Filtering and Formatting

Q: How do I create a custom report of requests?

A: Use format options and select specific fields for custom reporting.

Example:

# Custom CSV report
stoobly-agent request list \
  --select id --select method --select path --select created_at \
  --format csv \
  --without-headers > requests-report.csv

# JSON report with filtering
stoobly-agent request list \
  --scenario-key abc123 \
  --sort-by created_at \
  --sort-order asc \
  --format json > scenario-report.json

Q: How do I find requests by method?

A: Use the search option or filter the output.

Example:

# Search for POST requests
stoobly-agent request list --format json | jq '.[] | select(.method=="POST")'

# Search for GET requests to specific path
stoobly-agent request list --search "/api/users" --format json | jq '.[] | select(.method=="GET")'

Working with Remote Projects

Q: How do I list requests from a remote project?

A: Use the --project-key option to specify the remote project (remote features).

Example:

stoobly-agent request list --project-key proj-abc123

Q: How do I test against a remote project's endpoint definitions?

A: Use the --remote-project-key option when testing.

Example:

stoobly-agent request test xyz789 --remote-project-key proj-abc123

Troubleshooting

Q: How do I debug a failing request replay?

A: Increase log level and use verbose output.

Example:

stoobly-agent request replay xyz789 --log-level debug

Q: How do I see the full request and response details?

A: Use JSON format and query specific fields.

Example:

# Get full response
stoobly-agent request response get xyz789 --format json

# Query specific parts
stoobly-agent request response query xyz789 --query "$.headers"
stoobly-agent request response query xyz789 --query "$.body"

Q: What do I do if a request key is not found?

A: List all requests to find the correct key.

Example:

# List all requests to find the key
stoobly-agent request list

# Search for specific request
stoobly-agent request list --search "/api/endpoint"

Quick Reference

Q: What are the most common request commands?

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

Example:

# List requests
stoobly-agent request list
stoobly-agent request list --scenario-key abc123
stoobly-agent request list --search "/api/users"

# Replay requests
stoobly-agent request replay xyz789
stoobly-agent request replay xyz789 --host localhost:8080
stoobly-agent request replay xyz789 --record

# Test requests
stoobly-agent request test xyz789
stoobly-agent request test xyz789 --strategy diff
stoobly-agent request test xyz789 --strategy contract

# Snapshots
stoobly-agent request snapshot xyz789
stoobly-agent request reset xyz789

# View responses
stoobly-agent request response get xyz789
stoobly-agent request response query xyz789 --query "$.data"

# Delete requests
stoobly-agent request delete xyz789

# Manage logs
stoobly-agent request log list
stoobly-agent request log delete
PreviousInterceptNextRun

Last updated

Was this helpful?