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

```bash
stoobly-agent request list
```

#### Q: How do I paginate through requests?

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

**Example:**

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

```bash
stoobly-agent request list --scenario-key "<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:**

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

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

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

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

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

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

```bash
stoobly-agent request replay "<REQUEST-KEY>"
```

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

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

**Example:**

```bash
# Replay to localhost
stoobly-agent request replay "<REQUEST-KEY>" --host localhost:8080

# Replay to staging
stoobly-agent request replay "<REQUEST-KEY>" --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:**

```bash
# Force HTTP
stoobly-agent request replay "<REQUEST-KEY>" --scheme http

# Force HTTPS
stoobly-agent request replay "<REQUEST-KEY>" --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:**

```bash
stoobly-agent request replay "<REQUEST-KEY>" --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:**

```bash
stoobly-agent request replay "<REQUEST-KEY>" --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:**

```bash
stoobly-agent request replay "<REQUEST-KEY>" --record --scenario-key "<SCENARIO-KEY>"
```

#### Q: How do I format the replay response output?

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

**Example:**

```bash
# Body only
stoobly-agent request replay "<REQUEST-KEY>" --format body

# Full JSON with metadata
stoobly-agent request replay "<REQUEST-KEY>" --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:**

```bash
stoobly-agent request replay "<REQUEST-KEY>" --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:**

```bash
# Debug level (most verbose)
stoobly-agent request replay "<REQUEST-KEY>" --log-level debug

# Info level
stoobly-agent request replay "<REQUEST-KEY>" --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:**

```bash
# Assign single alias
stoobly-agent request replay "<REQUEST-KEY>" --assign userId=12345

# Assign multiple aliases
stoobly-agent request replay "<REQUEST-KEY>" --assign userId=12345 --assign token=abcde12345
```

#### Q: How do I validate alias values during replay?

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

**Example:**

```bash
# Validate userId is an integer
stoobly-agent request replay "<REQUEST-KEY>" --validate "userId=?int"

# Validate multiple aliases
stoobly-agent request replay "<REQUEST-KEY>" --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:**

```bash
# No alias resolution (default)
stoobly-agent request replay "<REQUEST-KEY>" --alias-resolve-strategy none

# First-in-first-out resolution
stoobly-agent request replay "<REQUEST-KEY>" --alias-resolve-strategy fifo

# Last-in-first-out resolution
stoobly-agent request replay "<REQUEST-KEY>" --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:**

```bash
# Replay once for each userId value
stoobly-agent request replay "<REQUEST-KEY>" --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:**

```bash
stoobly-agent request replay "<REQUEST-KEY>" --trace-id "<TRACE-ID>"
```

***

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

```bash
stoobly-agent request snapshot "<REQUEST-KEY>"
```

#### Q: How do I delete a request snapshot?

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

**Example:**

```bash
stoobly-agent request snapshot "<REQUEST-KEY>" --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:**

```bash
stoobly-agent request snapshot "<REQUEST-KEY>" --decode
```

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

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

**Example:**

```bash
stoobly-agent request reset "<REQUEST-KEY>"
```

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

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

**Example:**

```bash
stoobly-agent request reset "<REQUEST-KEY>" --force
```

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

**A:** Create snapshots and commit them to version control.

**Example:**

```bash
# Create snapshot
stoobly-agent request snapshot "<REQUEST-KEY>"

# 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 "<REQUEST-KEY>"  # Restore from snapshot
stoobly-agent request replay "<REQUEST-KEY>"  # Use the request
```

***

### Updating Requests

The following snapshot-based workflows are the **recommended approach** when updating single requests or requests that belong to an API endpoint.

#### Q: How do I update a single request?

**A:** Use the snapshot workflow to edit a request's data directly by modifying its snapshot file.

**Steps:**

1. Find the request key for the request you want to update:

```bash
stoobly-agent request list --search "/api/users"
```

2. Snapshot it using `stoobly-agent request snapshot "<REQUEST-KEY>"`. The output of the command is the snapshot file path:

```bash
stoobly-agent request snapshot "<REQUEST-KEY>"
```

3. Update the snapshot file. The format of the file is a raw HTTP request and response separated by a delimiter.
4. Run `stoobly-agent snapshot apply` to apply the updated snapshot to the database:

```bash
stoobly-agent snapshot apply
```

More details: [Editing with Snapshots](https://docs.stoobly.com/guides/how-to-update-requests/editing-with-snapshots), [Snapshot FAQ](https://docs.stoobly.com/faq/snapshot)

#### Q: How do I update all requests matching an API endpoint whose contract has changed?

**A:** When an API endpoint's request or response contract changes, use the snapshot workflow to update all matching requests in bulk.

**Steps:**

1. Find all request keys matching the endpoint pattern:

```bash
stoobly-agent request list --search "<PATTERN>" --select key --without-headers
```

Where `<PATTERN>` uses SQLite search syntax. For endpoints where a path segment is an ID (e.g., `/users/1`), the search pattern should be `/users/%`. The output will be request keys separated by newlines.

2. For each key in the search results, snapshot it using `stoobly-agent request snapshot "<REQUEST-KEY>"`. The output of the command is a snapshot file path for each key:

```bash
stoobly-agent request list --search "<PATTERN>" --select key --without-headers | while read key; do
  stoobly-agent request snapshot "$key"
done
```

3. For each path in the search results, update the snapshot file. The format of the files is raw HTTP requests and responses separated by a delimiter.
4. Run `stoobly-agent snapshot apply` to apply all updated snapshots to the database:

```bash
stoobly-agent snapshot apply
```

More details: [Editing with Snapshots](https://docs.stoobly.com/guides/how-to-update-requests/editing-with-snapshots), [Snapshot FAQ](https://docs.stoobly.com/faq/snapshot)

If you need to **update all requests within a scenario**, use the scenario-specific workflows described in the [Scenario FAQ](https://docs.stoobly.com/faq/scenario) and the [How to Update Scenarios](https://docs.stoobly.com/guides/how-to-update-requests/how-to-update-scenarios/) guide.

***

### Managing Request Responses

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

**A:** Use `request response show` to retrieve the stored response.

**Example:**

```bash
stoobly-agent request response show "<REQUEST-KEY>"
```

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

**A:** Use `request response query` with a query expression.

**Example:**

```bash
# Query JSON path
stoobly-agent request response query "<REQUEST-KEY>" --query "$.data.users[0].name"

# Query nested property
stoobly-agent request response query "<REQUEST-KEY>" --query "$.response.body"
```

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

**A:** Combine response query with shell processing.

**Example:**

```bash
# Extract user ID
userId=$(stoobly-agent request response query "<REQUEST-KEY>" --query "$.data.id")

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

# Extract array of values
stoobly-agent request response query "<REQUEST-KEY>" --query "$.data.users[*].email"
```

***

### Deleting Requests

#### Q: How do I delete a recorded request?

**A:** Use `request delete` with the request key.

**Example:**

```bash
stoobly-agent request delete "<REQUEST-KEY>"
```

#### Q: How do I delete multiple requests?

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

**Example:**

```bash
# Delete multiple specific requests
stoobly-agent request delete "<REQUEST-KEY-1>"
stoobly-agent request delete "<REQUEST-KEY-2>"
stoobly-agent request delete "<REQUEST-KEY-3>"

# Delete all requests from a scenario (scripted)
for key in $(stoobly-agent request list --scenario-key "<SCENARIO-KEY>" --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 logs list` to display all logged intercepted requests. Use `-f` to stream logs in real time, or filter by method, URL, status code, log level, and more.

**Examples:**

```bash
# List all intercepted request log entries
stoobly-agent request logs list

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

# Filter by HTTP method
stoobly-agent request logs list --method get

# Filter by URL substring
stoobly-agent request logs list --url /api/users

# Filter by HTTP status code
stoobly-agent request logs list --status-code 500

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

# Filter by log message
stoobly-agent request logs list --message "Mock failure"

# Filter by scenario name
stoobly-agent request logs list --scenario-name my-scenario

# Output as JSON
stoobly-agent request logs list --format json

# Select specific columns
stoobly-agent request logs list --select method,url,status-code

# Combine filters with follow
stoobly-agent request logs list --follow --level error --method post
```

#### Q: How do I clear the intercepted requests log?

**A:** Use `request logs delete` to truncate the log file.

**Example:**

```bash
stoobly-agent request logs delete
```

#### Q: How do I enable request logging?

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

**Example:**

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

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

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

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

**Example:**

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

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

```bash
# Replay multiple requests
for key in "<REQUEST-KEY-1>" "<REQUEST-KEY-2>" "<REQUEST-KEY-3>"; do
  stoobly-agent request replay $key
done

# Replay all requests in a scenario
for key in $(stoobly-agent request list --scenario-key "<SCENARIO-KEY>" --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:**

```bash
# Create initial snapshot
stoobly-agent request snapshot "<REQUEST-KEY>"

# Make changes and replay
stoobly-agent request replay "<REQUEST-KEY>" --overwrite

# Compare with snapshot
git diff .stoobly/snapshots/requests/<REQUEST-KEY>.json
```

#### Q: How do I chain requests with dependencies?

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

**Example:**

```bash
# First request creates a user, extract ID
userId=$(stoobly-agent request response query "<REQUEST-KEY-1>" --query "$.data.id")

# Second request uses that ID
stoobly-agent request replay "<REQUEST-KEY-2>" --assign "userId=$userId"
```

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

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

**Example:**

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

```bash
# 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 "<SCENARIO-KEY>" \
  --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:**

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

```bash
stoobly-agent request list --project-key "<PROJECT-KEY>"
```

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

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

**Example:**

```bash
stoobly-agent request test "<REQUEST-KEY>" --remote-project-key "<PROJECT-KEY>"
```

***

### Troubleshooting

#### Q: How do I debug a failing request replay?

**A:** Increase log level and use verbose output.

**Example:**

```bash
stoobly-agent request replay "<REQUEST-KEY>" --log-level debug
```

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

**A:** Use JSON format and query specific fields.

**Example:**

```bash
# Get full response
stoobly-agent request response show "<REQUEST-KEY>" --format json

# Query specific parts
stoobly-agent request response query "<REQUEST-KEY>" --query "$.headers"
stoobly-agent request response query "<REQUEST-KEY>" --query "$.body"
```

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

**A:** List all requests to find the correct key.

**Example:**

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

```bash
# List requests
stoobly-agent request list
stoobly-agent request list --scenario-key "<SCENARIO-KEY>"
stoobly-agent request list --search "/api/users"

# Replay requests
stoobly-agent request replay "<REQUEST-KEY>"
stoobly-agent request replay "<REQUEST-KEY>" --host localhost:8080
stoobly-agent request replay "<REQUEST-KEY>" --record

# Test requests
stoobly-agent request test "<REQUEST-KEY>"
stoobly-agent request test "<REQUEST-KEY>" --strategy diff
stoobly-agent request test "<REQUEST-KEY>" --strategy contract

# Snapshots
stoobly-agent request snapshot "<REQUEST-KEY>"
stoobly-agent request reset "<REQUEST-KEY>"

# View responses
stoobly-agent request response show "<REQUEST-KEY>"
stoobly-agent request response query "<REQUEST-KEY>" --query "$.data"

# Delete requests
stoobly-agent request delete "<REQUEST-KEY>"

# Manage logs
stoobly-agent request logs list
stoobly-agent request logs delete
```

***


---

# 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/request.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.