Bulk Management
restish bulk is a command-plugin workflow for checking out many API resources
to disk, editing them locally, and pushing changes back through Restish.
Prerequisites
- The
restish-bulkplugin binary is installed and discoverable. - The target API exposes collection and item URLs.
- You understand the API’s update semantics before pushing changes.
Verify discovery:
restish plugin list
restish bulk --help
Initialize A Checkout
The example API has a books collection used for bulk examples:
restish bulk init api.rest.sh/books
The plugin fetches the collection through Restish, writes resources to disk, and keeps metadata needed for later status, pull, reset, and push operations. Collection entries must include valid resource URLs. Relative URLs are resolved against the collection URL; malformed URLs stop the checkout with a clear error instead of creating partial local paths.
Daily Workflow
restish bulk status
restish bulk pull
restish bulk diff
restish bulk push
Use status before push so you know which local files changed and whether
remote updates exist.
Bulk metadata is saved atomically after completed file updates, so interrupted long pulls or pushes keep the last completed checkout state.
In a color-capable terminal, status labels, diffs, and projected JSON follow the configured Restish output theme. Piped output stays plain.
push is conservative. Updates and deletes require an HTTP validator
(ETag/Last-Modified) or matching local/remote version metadata. When that
evidence is missing or stale, the resource is refused instead of overwritten.
The push summary reports created, updated, deleted, skipped, and refused counts.
Use force only after reviewing the diff and accepting the overwrite risk:
restish bulk push --force
Reset Local Changes
restish bulk reset
restish bulk reset path/to/item.json
Reset discards local changes. Use it intentionally.
Matching Resources
Bulk operations can select resources with match expressions when the plugin supports the workflow:
restish bulk status --match 'rating_average >= 4.8'
When resources advertise JSON Schema with a describedby link or $schema
field, bulk uses that schema to warn about obvious match-expression type
mistakes.
Shape Mismatches
If your API uses different collection fields than the plugin expects, reshape responses with filters or configure the plugin according to its help output. Keep the HTTP work delegated to Restish so profiles, auth, retries, cache, and TLS behavior stay consistent.