Snapshot
Stoobly Snapshot CLI - Questions & Answers
The snapshot CLI manages version-controlled snapshots of requests and scenarios. Snapshots create committable files that enable team collaboration, historical tracking, and reproducible testing through version control systems like Git.
Understanding Snapshots
Q: What are snapshots in Stoobly?
A: Snapshots are version-controlled, file-based representations of requests and scenarios that can be committed to Git. They enable team collaboration and historical tracking of API tests.
Example:
# Create snapshot of a request
stoobly-agent request snapshot create "<REQUEST-KEY>"
# Create snapshot of a scenario
stoobly-agent scenario snapshot create "<SCENARIO-KEY>"
# Snapshots are stored in .stoobly/snapshots/
ls .stoobly/snapshots/requests/
ls .stoobly/snapshots/scenarios/Q: Why should I use snapshots?
A: Snapshots enable version control of your tests, team collaboration through Git, reproducible testing across environments, and historical tracking of API changes.
Example:
Q: What's the difference between requests in the database and snapshots?
A: Database requests are local and ephemeral, while snapshots are file-based, version-controlled, and shareable across the team.
Example:
Listing Snapshots
Q: How do I view all snapshots?
A: Use resource-specific list commands to display snapshots. List request snapshots with request snapshot list or scenario snapshots with scenario snapshot list.
Example:
Q: How do I list only request snapshots?
A: Use request snapshot list to display all request snapshots.
Example:
Q: How do I list only scenario snapshots?
A: Use scenario snapshot list to display all scenario snapshots.
Example:
Q: How do I search for specific snapshots?
A: Use the --search option with a regex pattern to filter snapshots. The search behavior depends on the resource type:
For request snapshots (using
request snapshot list): The regex matches from the start of the URL or the start of the path. For example,docs.stoobly.comwill not matchhttps://docs.stoobly.combecause the search starts from the beginning of the URL. Usehttps://docs.stoobly.comor.*?docs.stoobly.comto match URLs containing the domain.For scenario snapshots (using
scenario snapshot list): The regex matches from the start of the scenario name or the start of the scenario description.
Example:
Q: How do I filter snapshots by scenario key?
A: Use the --scenario-key option with request snapshot list to filter request snapshots that belong to a specific scenario.
Example:
Q: How do I list pending (unprocessed) snapshots?
A: Use the --pending flag with resource-specific list commands to show snapshots that haven't been applied yet.
Example:
Q: How do I limit the number of snapshots displayed?
A: Use the --size option with resource-specific list commands to control the number of results.
Example:
Q: How do I format snapshot list output?
A: Use the --format option with resource-specific list commands to change output format.
Example:
Q: How do I select specific columns to display?
A: Use the --select option with resource-specific list commands to choose which columns to show.
Example:
Applying Snapshots
Q: How do I apply all snapshots?
A: Use snapshot apply without arguments to apply all available snapshots.
Example:
Q: How do I apply a specific snapshot?
A: Use snapshot apply with the snapshot UUID.
Example:
Q: What happens when I apply a snapshot?
A: Applying a snapshot creates or updates the corresponding request or scenario in your local database from the snapshot file.
Example:
Q: How do I force apply snapshots with hard delete?
A: Use the --force flag to hard delete existing resources when applying.
Example:
Q: What's the difference between apply and reset?
A: These commands serve different purposes:
snapshot apply: Creates or updates requests/scenarios in your database from snapshot files. Use this when you have snapshot files (e.g., after pulling from git) and want to build your database from them. This is a bulk operation that processes snapshot files.request resetorscenario reset: Reverts a specific request or scenario that already exists in your database back to its snapshot state. Use this when you've made changes to a request/scenario and want to undo those changes by restoring from its snapshot.
Example:
Updating Snapshots
Q: How do I create/update a request snapshot?
A: Use request snapshot create with the request key to create or update a request snapshot.
Example:
Q: How do I create/update a scenario snapshot?
A: Use scenario snapshot create with the scenario key to create or update a scenario snapshot.
Example:
Q: How do I update a snapshot without verification?
A: Use the --no-verify flag to skip request verification.
Example:
Q: What does snapshot verification do?
A: Verification ensures the raw HTTP request format is valid and fixes any formatting issues before creating the snapshot.
Example:
Resetting Snapshots
Q: How do I reset a request to its snapshot state?
A: Use request snapshot reset with the request key to revert a request back to its last snapshot state. This will discard any changes made to the request since the snapshot was created.
Example:
Q: What happens when I reset a request?
A: Reset will:
Load the request data from the last snapshot file
Overwrite the current request in your local database with snapshot data
Restore the exact request state from when the snapshot was created
Discard all changes made since the snapshot was created
Example:
Q: How do I know what will be lost when I reset?
A: Use request snapshot diff to preview changes before resetting.
Example:
Q: How do I reset a request with force delete?
A: Use the --force flag to hard delete the request before restoring it from snapshot. This is useful if the request is in a corrupted state.
Example:
Q: What's the difference between reset with and without --force?
A:
Without
--force: Updates the existing request with snapshot data. Safer option that preserves record history.With
--force: Hard deletes the request completely, then recreates it from snapshot. Use this if the request is corrupted or if you want a clean state.
Example:
Q: Can I undo a reset?
A: No, reset is permanent. Once a reset is applied, the changes are lost. However, you can:
Use
request snapshot diffbefore resetting to understand what will changeCheck Git history if you have snapshots committed
Use your database backups if available
Example:
Q: How do I reset a scenario to its snapshot state?
A: Use scenario snapshot reset with the scenario key to revert a scenario back to its last snapshot state.
Example:
Q: What happens when I reset a scenario?
A: Reset will:
Load the scenario metadata from the last snapshot file
Update the scenario name and description from the snapshot
Restore all requests in the scenario to their snapshot states
Discard all changes made to the scenario and its requests since the snapshot
Example:
Q: How do I know what will be lost when I reset a scenario?
A: Use scenario snapshot diff to preview all changes before resetting.
Example:
Q: How do I reset a scenario with force delete?
A: Use the --force flag to hard delete the scenario before restoring it from snapshot.
Example:
Q: When should I use reset?
A: Reset is useful when:
You made accidental changes to requests or scenarios
You want to undo modifications and return to a known good state
You want to sync with the committed snapshot in Git
You need to verify that the snapshot is still valid
The scenario got corrupted and needs a clean restore
Example Workflow:
Q: Can I reset multiple requests or scenarios at once?
A: Use a script to reset multiple resources.
Example:
Q: What's the difference between reset and apply?
A:
reset: Reverts a specific resource (request or scenario) back to its snapshot state. Works on individual resources you've already modified.apply: Applies snapshots from snapshot files to create or update resources in your database. Works on unprocessed snapshots (typically after pulling from Git).
Example:
Global Snapshot Reset
Q: How do I reset all requests and scenarios to their snapshot states at once?
A: Use snapshot reset (without a resource key) to reset all requests and scenarios that have snapshots back to their last snapshot state. This is useful when you've made many changes and want to reset everything.
Example:
Q: What happens when I run snapshot reset?
A: The command will:
Count all requests and scenarios that have snapshots
Ask for confirmation (unless
--yesis used)Reset each resource to its snapshot state
Report success/failure count for the operation
Example:
Q: How do I skip the confirmation prompt?
A: Use the --yes flag to proceed without confirmation. Useful for automated scripts.
Example:
Q: What's the --hard option for snapshot reset?
A: The --hard flag deletes ALL requests and scenarios in your database before resetting them from snapshots. This is a destructive operation that should be used carefully.
Important: --hard will delete:
All requests not in snapshots
All scenarios not in snapshots
All requests in snapshots (they'll be recreated)
All scenarios in snapshots (they'll be recreated)
Example:
Q: When should I use --hard?
A: Use --hard in these situations:
Clean slate needed: You want to remove all local changes and start fresh from snapshots
Database corruption: Your database has inconsistent or corrupted data
Fresh environment setup: Setting up a new environment from snapshots
Testing snapshot integrity: Verify that all snapshots can be applied cleanly
Cleanup: Remove clutter and unwanted requests/scenarios not in snapshots
Example Workflows:
Q: What's the difference between --hard and normal reset?
A:
Deletes unsnapshot items?
No
Yes
Deletes snapshot items?
No
Yes (recreates them)
Safe for normal use?
Yes
No (destructive)
Data loss risk?
Low
High
Best for?
Undo changes
Fresh start
Example:
Q: What should I do before using --hard?
A: Before using --hard, take these safety measures:
Backup your database
Review what will be deleted with
snapshot listCommit snapshots to Git
Consider the impact on your team
Example Safety Workflow:
Q: Can I undo a hard reset?
A: Hard reset is permanent. To recover:
Restore from backup: If you created a database backup
Restore from Git: If you committed snapshots before the reset
Re-record data: If you have the original traffic
Example Recovery:
Q: How does --lock-timeout work?
A: The --lock-timeout option prevents concurrent reset operations that could corrupt your database. Only one reset can run at a time within the specified timeout.
Example:
Q: Can I reset while other processes are running?
A: The lock mechanism ensures only one snapshot reset can run at a time. However, it's best practice to:
Stop your application
Stop the Stoobly agent if running
Run the reset
Restart applications
Example Safe Reset:
Q: How do I use snapshot reset in scripts or CI/CD?
A: Use the --yes flag to skip confirmation, and check exit codes to handle errors.
Example Bash Script:
Example GitHub Actions:
Q: What error messages might I see?
A: Common error messages and what they mean:
"Another snapshot reset command is already running": Wait for the other reset to complete
"Completed with X failures (Y succeeded)": Some resources failed to reset; check error logs
"Aborted.": You rejected the confirmation prompt
Example Troubleshooting:
Q: What counts as a "snapshot" for the reset operation?
A: Snapshots are counted from the snapshot log. Only requests and scenarios with PUT_ACTION events in the snapshot log are included.
Example:
Comparing Snapshots
Q: How do I see the diff between a request and its snapshot?
A: Use request snapshot diff to show differences between the current request stored in your database and its last snapshot state.
Example:
Q: What information does the diff show for a request?
A: The diff displays:
Current request data from your local database
Snapshot request data from the last saved version
Detailed comparison of request properties (URL, method, headers, body)
Response body comparisons
Example:
Q: How do I see the full raw diff for all requests?
A: Use the --full flag to display the complete raw HTTP request diff for a specific request.
Example:
Q: What does the --full flag show?
A: The --full flag displays the complete raw HTTP request format, showing exactly how the request has changed at the HTTP level.
Example:
Q: How do I see diffs for all requests that have changed?
A: Run request snapshot diff without specifying a request key to see diffs for all requests with snapshots.
Example:
Q: How do I see the diff between a scenario and its snapshot?
A: Use scenario snapshot diff to show differences between the current scenario stored in your database and its last snapshot state.
Example:
Q: What information does the scenario diff show?
A: The scenario diff displays:
Scenario metadata changes (name, description)
Request changes within the scenario
For each request: added/removed/modified properties
Overall scenario composition differences
Example:
Q: How do I see full raw diffs for all requests in a scenario?
A: Use the --full flag to display complete raw HTTP diffs for all requests in the scenario.
Example:
Q: How do I see diffs for all scenarios that have changed?
A: Run scenario snapshot diff without specifying a scenario key to see diffs for all scenarios with snapshots.
Example:
Q: When should I use diff before resetting?
A: Always check the diff before resetting to ensure you want to discard the changes. The diff shows you exactly what will be lost.
Example:
Q: Can I use diff to find requests that match a pattern?
A: The request snapshot diff command will show diffs for all requests with snapshots. You can filter by specifying a request key or by piping output.
Example:
Copying Snapshots
Q: How do I copy snapshots to a different directory?
A: Use snapshot copy with the destination path to copy snapshots between data directories.
Example:
Q: How do I copy multiple requests at once?
A: Use multiple --request-key options to copy several requests.
Example:
Q: How do I copy multiple scenarios at once?
A: Use multiple --scenario-key options to copy several scenarios.
Example:
Q: How do I copy both requests and scenarios together?
A: Combine both --request-key and --scenario-key options.
Example:
Q: Why would I copy snapshots to a different directory?
A: Copying snapshots is useful for moving tests between projects, creating backups, or setting up separate test environments.
Example:
Pruning Snapshots
Q: How do I clean up deleted snapshots?
A: Use snapshot prune to remove snapshot files for deleted resources.
Example:
Q: How do I preview what will be pruned without deleting?
A: Use the --dry-run flag to see what would be deleted.
Example:
Q: When should I prune snapshots?
A: Prune after deleting scenarios or requests to keep your snapshot directory clean and your Git repository size manageable.
Example:
Version Control Workflows
Q: How do I set up snapshots for Git?
A: Create snapshots and add the .stoobly/snapshots/ directory to Git.
Example:
Q: How do team members use snapshots from Git?
A: Pull the repository and apply snapshots to get the tests.
Example:
Q: How do I update existing snapshots in Git?
A: Re-create the snapshot and commit the changes.
Example:
Q: How do I handle merge conflicts in snapshots?
A: Resolve conflicts manually in snapshot files or re-create snapshots from one version.
Example:
Q: Should I commit snapshot files or the database?
A: Commit snapshot files in .stoobly/snapshots/, NOT the database files in .stoobly/db/. Add .stoobly/db/ to .gitignore.
Example:
Advanced Snapshot Operations
Q: How do I export snapshots for backup?
A: Copy the .stoobly/snapshots/ directory or use snapshot copy.
Example:
Q: How do I share snapshots across projects?
A: Use snapshot copy to move snapshots between project directories.
Example:
Q: How do I create snapshots in CI/CD?
A: Record requests during CI, create snapshots, and commit them back if needed.
Example:
Q: How do I validate snapshots in CI/CD?
A: Apply snapshots and run tests to ensure they're valid.
Example:
Troubleshooting
Q: What do I do if snapshot apply fails?
A: Check for errors, use force option, or manually inspect the snapshot files.
Example:
Q: How do I verify snapshot integrity?
A: Use snapshot create to verify and fix snapshot formatting.
Example:
Q: How do I find which snapshot corresponds to a request?
A: List snapshots with search or match request keys to UUIDs.
Example:
Best Practices
Q: When should I create snapshots?
A: Create snapshots after recording important test flows, before releases, and when sharing tests with the team.
Example:
Q: How often should I prune snapshots?
A: Prune after deleting old tests or periodically to keep the repository clean.
Example:
Q: When should I decode snapshots?
A: Use --decode when creating snapshots for better Git diffs and readability.
Example:
Quick Reference
Q: What are the most common snapshot commands?
A: Here's a quick reference of frequently used commands:
Example:
Integration Examples
Q: How do I automate snapshot creation?
A: Use a script to create snapshots for all scenarios.
Example:
Q: How do I sync snapshots across environments?
A: Use Git to sync and snapshot copy for different data directories.
Example:
Last updated