Skip to content

Download an archive#

An archive is a tar.gz or zip containing the output a BSR plugin would have produced for a specific module commit. Reach for an archive when a plugin doesn’t have a BSR-hosted package-manager registry: JSON Schema, BigQuery, and most custom plugins fall in this bucket. Plugins for languages with a dedicated registry (Go, npm, Maven, Python, Cargo, NuGet, Swift, CMake) install through that registry instead, and the BSR hides the Download archive link for them.

The running example below pairs the connectrpc/eliza module with the bufbuild/protoschema-jsonschema plugin.

What’s in an archive#

The archive contains a single top-level directory named <module>_<plugin> (for example, eliza_protoschema-jsonschema) with the plugin’s output beneath it. Source .proto files aren’t included; the archive carries only what the plugin generated.

Download from the BSR web app#

  1. Open the module and click the SDKs tab.
  2. Choose the plugin.
  3. Optionally change the plugin version or module label using the dropdowns.
  4. Click Download archive at the top right of the SDK section, choose tar.gz or zip, and click Download (or copy the URL to use with curl).

Download with the BSR API#

The curl form takes the module, plugin, reference, and file extension:

URL grammar
$ curl -fsSL -O https://BSR_INSTANCE/gen/archive/ORGANIZATION/MODULE_NAME/PLUGIN_OWNER/PLUGIN_NAME/REFERENCE.FILE_EXT

The placeholders:

  • BSR_INSTANCE is the BSR host (defaults to buf.build).
  • ORGANIZATION is the BSR organization that owns the module.
  • MODULE_NAME is the module name.
  • PLUGIN_OWNER and PLUGIN_NAME identify the plugin.
  • REFERENCE is one of:
    • latest: latest commit on the module’s default label, latest plugin version.
    • A label name: latest commit on that label, latest plugin version.
    • A full module commit ID: that commit, latest plugin version.
  • FILE_EXT is tar.gz or zip.

The endpoint always returns a 302 redirect to the actual download URL. curl -L follows it; clients that don’t follow redirects by default must handle the 302 themselves.

Examples
$ # Latest commit on the default label.
$ curl -fsSL -O https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/latest.zip

$ # Latest commit on a specific label.
$ curl -fsSL -O https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/demo.zip

$ # A specific module commit.
$ curl -fsSL -O https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/8bde2b90ec0a7f23df3de5824bed0b6ea2043305.zip

Include imports and Well-Known Types#

Add the imports and wkt query parameters to control what the archive includes. They behave like --include_imports and --include_wkt on buf generate.

Set both to include the Well-Known Types alongside other imports:

$ curl -fsSL -O "https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/latest.zip?imports=true&wkt=true"

Pin to a specific plugin version and module commit#

The latest and label references resolve at request time, so the BSR uses the latest plugin version for them. To pin both the module commit and the plugin, use a fully resolved reference instead:

Pinned reference URL
$ curl -fsSL -O https://BSR_INSTANCE/gen/archive/ORGANIZATION/MODULE_NAME/PLUGIN_OWNER/PLUGIN_NAME/vX.Y.Z-commit.N.FILE_EXT

The components:

  • vX.Y.Z is the plugin version.
  • commit is the 12-character module commit short name.
  • N is the plugin revision.

You can read these values off the sample URL on the SDK’s installation page.

Examples
$ curl -fsSL -O https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/v0.5.0-233fca715f49.1.zip
$ curl -fsSL -O "https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/v0.5.0-233fca715f49.1.zip?imports=true"
$ curl -fsSL -O "https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/v0.5.0-233fca715f49.1.zip?imports=true&wkt=true"

Access individual files#

The BSR also serves the raw contents of an archive at a subpath of the same endpoint, so callers can fetch one file without unpacking the archive. This works for any archive-producing plugin’s output:

Raw file URL
https://BSR_INSTANCE/gen/archive/ORGANIZATION/MODULE_NAME/PLUGIN_OWNER/PLUGIN_NAME/raw/REFERENCE/FILE_PATH

Raw-file URLs redirect only when REFERENCE isn’t already a fully resolved version (vX.Y.Z-commit.N); fully resolved references serve the file directly.

Reference a JSON Schema file#

For schemas generated by the protoschema-jsonschema plugin, the raw-file URL points at a single JSON Schema document:

JSON Schema URL
https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/raw/latest/connectrpc.eliza.v1.ConverseRequest.schema.json

YAML language servers and IDEs can use that URL to provide auto-completion against a BSR-generated schema:

YAML language-server schema reference
# yaml-language-server: $schema=PATH_TO_SCHEMA

# Reference a BSR-generated schema
# yaml-language-server: $schema=https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/raw/latest/connectrpc.eliza.v1.ConverseRequest.schema.json

Private modules#

For archives generated from private BSR modules, send a BSR token on the curl request:

$ curl -fsSL -O \
    -H "Authorization: Bearer ${BUF_TOKEN}" \
    https://buf.build/gen/archive/your-org/your-module/your-plugin-owner/your-plugin/latest.zip

Use a personal API token for local downloads or a bot user token in automation; see Authentication for token setup.