Librarian CLI

This repository contains code for a unified command line tool for Google Cloud SDK client library configuration, generation and releasing.

See CONTRIBUTING.md for a guide to contributing to this repository, and the doc/ folder for more detailed project documentation.

The Librarian project supports the Google Cloud SDK ecosystem, and we do not expect it to be of use to external users. That is not intended to discourage anyone from reading the code and documentation; it's only to set expectations. (For example, we're unlikely to accept feature requests for external use cases.)

Installation

Install Go and make sure you have you have the following in your PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Next install the CLI

go install github.com/googleapis/librarian/cmd/librarian@latest

Running Librarian

To see the current set of commands available, run:

librarian -help

Use the -help or -h flag for any individual command to see detailed documentation for its purpose and associated flags. For example:

librarian generate -h

Alternatively, if you prefer not to have librarian installed you can use the Go command to run the latest released version:

go run github.com/googleapis/librarian/cmd/librarian@latest -help

Setup and Configuration

To run librarian, you will need to configure a Github Token and set it to the LIBRARIAN_GITHUB_TOKEN environment variable. This will use the Github token as authentication to push to Github and to run Github API commands (e.g. Creating a PR and Adding Labels to a PR).

Unless specifically configured, Librarian will use HTTPS for pushing to remote. See the SSH section for push to remote via SSH.

Github Token

There are two main options to get a Github token:

1. Use the gh cli tool to easily authenticate with github. Run the following commands once the tool is installed:

# Follow the instructions from the tool. If using SSH, see the section
# below regarding additional setup.You still need a Github Token to run
# Github API commands (e.g. creating a pull request).
gh auth login 
# This will output the token to use as the Github Token
gh auth token

This will create a token with the repo scope.

2. Alternatively, follow the steps listed in the Github guide to create a Personal Access Token (PAT). You will need the repo scope for your token.

Once you have created a token, set the token as the environment variable:

export LIBRARIAN_GITHUB_TOKEN={YOUR_TOKEN_HERE}

Using SSH

There are two main ways to configure SSH:

1. Using the gh cli to upload your SSH public key to Github. When following the steps in the gh cli tool, you will select your public key to be added to Github. Additionally, you will need to add your private key to the ssh-agent.

Typically, your private keys will be ~/.ssh/id_ed25519 or ~/.ssh/id_rsa and your public keys will be the same with the .pub suffix. You should be able to see this by running ls ~/.ssh. If you do not see a public/ private key combination, you can follow this guide to generate a new key.

Running the following commands to add your private key to ssh-agent:

# This will start the ssh-agent if it hasn't already been started
eval "$(ssh-agent -s)"

# This adds your private key to the ssh-agent.
# Note: The private key will not have the `.pub` suffix.
ssh-add ~/.ssh/{PRIVATE_KEY_FILE}

# Run this command to verify that your private key is added
# You should see an output of a SHA with an absolute path to the private key
# e.g. `256 SHA:{MY_SHA} .../.ssh/id_ed25519`
ssh-add -l

2. Follow the steps here. You will need to either create a new SSH key or using an existing one, add it to the ssh-agent, and then upload it to Github.

Once everything has been configured, set the origin remote to the SSH URI:

git remote set-url origin [email protected]:googleapis/librarian.git

Documentation

• CLI Documentation
• Language Onboarding Guide
• How We Write Go
• State Schema
• Config Schema
• Running Tests
• sidekick

License

Apache 2.0 - See LICENSE for more information.