Marketplace / Docs / Bundles

Collections & Bundles

Discover, install, and create bundles — curated sets of packages that install together as a single unit.

Jump to section

How to discover, install, and create bundles — curated sets of packages that install together as a single unit.

Overview

A bundle is a named, curated set of packages that can be browsed, priced, and installed together. Bundles are useful for "starter kit" experiences (a coding agent + its tools + its prompts), for shipping a team's standard stack as a single install, or for selling a coherent product made of multiple packages at a discount.

Each bundle has a slug (URL handle), display_name, description, bundle_type, an ordered list of member packages, and optional pricing.

UI Status

Note: The marketplace web UI does not yet have a dedicated bundle browse page. The CLI commands and REST API documented below are live today — use the CLI to discover, inspect, and install bundles. A web surface for browsing curated bundles is planned.

Bundle Types

The registry recognizes three bundle_type values:

  • curated — assembled by marketplace staff to highlight a theme (e.g. "Web Scraping Starter Kit").
  • publisher — created by a publisher to bundle their own packages.
  • official — first-party bundles from the Snippbot team.

The bundle type is set at creation and shows up in CLI listings and API responses.

Browsing Bundles

List available bundles with pagination:

snippbot marketplace bundles
snippbot marketplace bundles --page 2
snippbot marketplace bundles --json

The default text output is a table with columns: Bundle (display name), Type, Packages (member count), Price, Installs. Use --json for machine-readable output that includes the full BundleResponse fields.

Under the hood this hits GET /api/v1/bundles?page=<n>.

Inspecting a Bundle

Show full details for a single bundle by slug:

snippbot marketplace bundle-info <slug>

The output shows the display name, slug, type, price (or "Free"), discount percentage if any, lifetime install count, the description, and the list of included packages.

API: GET /api/v1/bundles/{slug}. The response includes a packages array with each member's package ID and metadata.

Installing a Bundle

snippbot marketplace bundle-install <slug>

This calls POST /api/v1/bundles/{slug}/install, which initiates installation of every package the bundle contains. The CLI prints a confirmation and any server-side message; individual package installs follow the same flow as marketplace install would for each one.

If the bundle is paid, the install endpoint enforces the same purchase requirements as installing a paid package directly.

Creating a Bundle

Bundle creation is API-only today. To create a bundle programmatically:

POST /api/v1/bundles
Authorization: Bearer <token-or-api-key>

{
  "slug": "web-scraping-starter",
  "display_name": "Web Scraping Starter Kit",
  "description": "A curated set of agents, tools, and prompts for getting started with web scraping in Snippbot.",
  "bundle_type": "publisher",
  "cover_image_url": "https://example.com/cover.png"
}

Slug rules (enforced server-side):

  • 2-128 characters.
  • Lowercase alphanumeric and hyphens.
  • Cannot start or end with a hyphen.

display_name is 1-256 characters; description is 1-5000 characters; bundle_type must be one of curated, publisher, official (note that only marketplace admins should set curated/official — the API will accept a publisher creating one only if they have the right role).

Adding and Removing Packages

Bundles are built by adding packages one at a time. Each member has a sort_order integer that controls display order.

POST /api/v1/bundles/{slug}/packages
{
  "package_id": "<uuid>",
  "sort_order": 1
}

DELETE /api/v1/bundles/{slug}/packages/{package_id}

List the current members:

GET /api/v1/bundles/{slug}/packages

A bundle's package_count updates automatically as you add or remove members.

Publishing a Bundle

Newly created bundles are draft by default. To publish:

PATCH /api/v1/bundles/{slug}
{ "is_published": true }

Once is_published is true, the bundle appears in the public listing endpoints and the CLI bundles command. Set it back to false to unpublish (still accessible by slug for testing, but no longer listed).

You can also update display_name, description, cover_image_url, and pricing fields through the same PATCH.

Pricing and Discounts

Bundles support paid pricing in addition to bundle-level discounts:

  • is_paid: true + price_cents: <0-99999> + currency: "USD" — sets the bundle price.
  • discount_percent: <0-50> — optional percent discount applied at install time, intended for "buy the bundle for X% off vs. all packages individually".

Free bundles (the default) leave is_paid as false and don't require any price fields. Currency is a 3-letter ISO 4217 code; pricing today is USD-centric.

CLI Reference

For full flags and subcommands, see the Snippbot CLI reference.

Bundle-related commands:

  • snippbot marketplace bundles [--page N] [--json] — list available bundles.
  • snippbot marketplace bundle-info <slug> [--json] — show full details for a bundle.
  • snippbot marketplace bundle-install <slug> — install every package in the bundle.

Bundle creation, editing, and member management are currently API-only — call the endpoints described above directly with your API key.