librarian

Overview ¶

Librarian manages Google Cloud client libraries. It runs a local workflow that onboards new APIs, generates client code, bumps versions, publishes releases, and tags release commits. Language-specific work, such as code generation, building, and testing, is delegated to per-language tooling.

All behavior is driven by librarian.yaml at the root of the repository, whose schema is documented at https://github.com/googleapis/librarian/blob/main/doc/config-schema.md.

Usage:

librarian <command> [arguments]

Global flags:

--verbose, -v    enable verbose logging

Read and write librarian.yaml configuration ¶

Usage:

librarian config [get|set] [path] [value]

Get a configuration value ¶

Usage:

librarian config get [path]

Set a configuration value ¶

Usage:

librarian config set [path] [value]

Add a new client library ¶

Usage:

librarian add <api>

add registers a single API in librarian.yaml.

The <api> is a path within the configured googleapis source, such as "google/cloud/secretmanager/v1". The library name and other defaults are derived from the first API path using language-specific rules.

If the API path should naturally be included in an existing library, and if the language supports doing so, that library is modified. Otherwise, a new library is created.

To add a preview client of an existing library, prefix the API path with "preview/".

Examples:

librarian add google/cloud/secretmanager/v1
librarian add preview/google/cloud/secretmanager/v1beta

A typical librarian workflow for adding a new client library is:

librarian add <api>            # onboard a new API into librarian.yaml
librarian generate <library>   # generate the client library

Generate a client library ¶

Usage:

librarian generate <library>

generate produces client library code from the APIs configured in librarian.yaml.

The library name argument selects a single library to regenerate. Use the --all flag to regenerate every library in the workspace instead. Exactly one of <library> or --all must be provided.

Generation is delegated to the language-specific tooling configured in librarian.yaml. Libraries marked with skip_generate are skipped.

Examples:

librarian generate <library>   # regenerate one library
librarian generate --all       # regenerate every library

Flags:

--all       generate all libraries

A typical librarian workflow for regenerating every library against the latest API definitions is:

librarian update googleapis
librarian generate --all

Bump version numbers and prepare release artifacts ¶

Usage:

librarian bump <library>

bump updates version numbers and prepares the files needed for a new release.

If a library name is given, only that library is updated. The --all flag updates every library in the workspace. When a library is specified explicitly, the --version flag can be used to override the new version.

Examples:

librarian bump <library>           # update version for one library
librarian bump --all               # update versions for all libraries

Flags:

--all             update all libraries in the workspace
--version string  specific version to update to; not valid with --all

Install tool dependencies for a language ¶

Usage:

librarian install [language]

install installs the language-specific tools that librarian uses to generate and build client libraries (for example, language SDKs and code generators).

If [language] is omitted, the language is read from librarian.yaml in the current directory.

Examples:

librarian install              # use language from librarian.yaml
librarian install go           # install Go-specific tools

Tidy and validate librarian.yaml ¶

Usage:

librarian tidy

tidy reads librarian.yaml, validates its contents, applies any language-specific defaults and normalization, and writes the file back with a canonical formatting.

Run tidy after editing librarian.yaml by hand, or as a quick check that the configuration is well-formed.

Update sources or version to the latest version ¶

Usage:

librarian update <version | source>...

update refreshes the upstream source repositories declared in librarian.yaml to their latest commits and updates the recorded commit SHAs in librarian.yaml accordingly. It also supports updating the librarian version.

Supported targets:

• conformance: protocolbuffers/protobuf conformance tests
• discovery: googleapis/discovery-artifact-manager
• googleapis: googleapis/googleapis (the API definitions)
• protobuf: protocolbuffers/protobuf
• showcase: googleapis/gapic-showcase
• version: the librarian tool version

At least one target must be specified.

Examples:

librarian update googleapis
librarian update googleapis protobuf
librarian update version

A typical librarian workflow for regenerating every library against the latest API definitions is:

librarian update googleapis
librarian generate --all

Publish client libraries ¶

Usage:

librarian publish

publish releases the libraries that were updated in a release commit prepared by librarian bump.

By default, publish performs a dry run that prints the actions it would take. Pass --execute to actually publish. By default, the most recent release commit reachable from HEAD is used; --release-commit overrides this with a specific commit.

The --dry-run, --dry-run-keep-going, and --skip-semver-checks flags are only honored when the workspace language is Rust; they are retained for backwards compatibility with the legacy Rust release jobs and will be removed once Rust migrates to the unified flow.

Examples:

librarian publish                          # dry run
librarian publish --execute                # publish for real
librarian publish --release-commit=<sha>   # publish a specific commit

Flags:

--execute                fully publish (default is to only perform a dry run)
--release-commit string  the release commit to publish; default finds latest release commit
--dry-run                print commands without executing (legacy Rust-only flag)
--dry-run-keep-going     print commands without executing, don't stop on error (legacy Rust-only flag)
--skip-semver-checks     skip semantic versioning checks (legacy Rust-only flag)
--verbose, -v            streams output of publishing commands executed

Tag a release commit based on the libraries published ¶

Usage:

librarian tag

tag creates git tags on a release commit, one tag per library that the commit released, using the tag_format declared for each library in librarian.yaml.

Run tag after librarian publish has succeeded. By default, the most recent release commit reachable from HEAD is used; --release-commit overrides this with a specific commit.

The --create-release-tag flag additionally creates a tag of the form release-<PR number>; this is used by the legacy release jobs and will be removed once those jobs are retired.

Examples:

librarian tag
librarian tag --release-commit=<sha>
librarian tag --create-release-tag

Flags:

--release-commit string  the release commit to tag; default finds latest release commit
--create-release-tag     whether to create a tag of the form release-{PR number}

Print the binary version ¶

Usage:

librarian version

version prints the librarian binary version and exits. The version is embedded at build time and follows the conventions described at https://go.dev/ref/mod#versions.