Hyaline Hyaline

How To: Use Hyaline From Scratch (Advanced)

Purpose

Run Hyaline from scratch without using the GitHub App

Prerequisite(s)

Steps

1. Install CLI

You can either download a pre-built version from GitHub (1.1) or build the CLI yourself (1.2)

1.1 Download CLI

Before starting the installation process you need to determine your operating system and architecture. Hyaline supports 64-bit Linux (linux), MacOS (darwin), and Windows (windows) operating systems for either amd64 or arm64 architectures (amd64 only for Windows).

You can download the appropriate binary from the Release Page on GitHub. Just select the release you would like to use and get the link to the appropriate binary from the assets section.

Alternatively you can use the following URL template: https://github.com/appgardenstudios/hyaline/releases/download/{RELEASE}/hyaline-{OS}-{ARCH}.zip.

Depending on your operating system you will need to do one or more of the following:

  • Unzip the downloaded executable
  • Make hyaline executable (if applicable)
  • Add hyaline to your PATH (if desired)

1.2 Build CLI

Ensure that the Hyaline Repository is cloned and checked out to the version you wish to build. Once the version is checked out you can build hyaline using the following command (from the root of the repo):

$ go build -o ./dist/hyaline -ldflags="-X 'main.Version=$VERSION'" ./cmd/hyaline.go

Note: Hyaline uses the pattern v1YYYY-MM-DD-HASH for release versions, and defaults to the version unknown when main.Version is not set via flag

You can specify the OS and architecture to use by setting the appropriate GOOS/GOARCH environment variables. For example, to build for the 64bit ARM version of MacOS:

$ GOOS=darwin GOARCH=arm64 go build -o ./dist/hyaline -ldflags="-X 'main.Version=$TAG'" ./cmd/hyaline.go

2. Run the CLI

First run hyaline version to ensure that the Hyaline CLI is installed and working properly.

Most commands require a hyaline configuration file. You will need to pass the path of the file in as the value of the --config commandline parameter. Either locate or create that configuration file now. For more information on the format of the configuration file please see the Hyaline Config Reference.

Based on the contents of the configuration file above there may be one or more environment variables that need to be set before running Hyaline. You can find these in the config by looking for references like ${MY_VAR}, which specifies that Hyaline should use the value of the environment variable MY_VAR for that key in the config.

Now you can execute the hyaline command, passing in all of the required and (optionally) optional parameters. Please see CLI Reference for a full list of commands and their associated options.

3. Extract Documentation

To extract documentation you need to create a configuration file (3.1) and then run Hyaline to extract your documentation (3.2).

Step 3.1 Create a Configuration File

Create a hyaline.yml file in your project root. Here’s basic configuration to extract documentation from a typical project that has a locally checked-out git repo and main branch:

extract:
  source:
    id: my-app
    description: My application documentation
  crawler:
    type: git
    options:
      path: .
      branch: main
    include:
      - "**/*.md"
    exclude:
      - "node_modules/**/*"
      - ".git/**/*"
  extractors:
    - type: md
      include:
        - "**/*.md"

Configuration Breakdown

  • extract: Top-level key for extraction configuration
  • source: Metadata about the documentation source (id and description)
  • crawler: Specifies how to crawl the documentation (git repository in this case)
  • extractors: List of extractors to process documentation files (markdown in this case)

Note that the above configuration is for a simple example, but Hyaline can be configured to extract documentation from multiple systems and sources (e.g. websites, remote git repositories). For complete configuration options and details, see the Configuration Reference.

Step 3.2: Extract Documentation

Now run Hyaline to extract your documentation into a data set (note that you will need to run this from the root of the documentation source):

$ hyaline extract documentation \
  --config ./hyaline.yml \
  --output ./documentation.db

This command will:

  • Scan your repository for documentation files based on the configuration
  • Extract and process them according to the defined extractors
  • Store everything in a SQLite database (documentation.db)

For more details on how extraction works, see Explanation: Extract.

4. Check a PR

To check a GitHub pull request you need to check in your configuration file (4.1), set up the required secrets (4.2), and then create a GitHub Workflow file to run a GitHub Action to check a pull request (4.3).

4.1 Check in Configuration

Create a Hyaline Configuration File with extract and check configured, and check it into your GitHub repository.

Make sure you don’t check in any secrets, like the LLM Provider Key or the GitHub Token. Instead, set up the configuration to pull them from the environment.

See config reference for more information on creating a configuration file and referencing secrets.

4.2. Set Up Secrets

For each environment variable used in the Hyaline configuration that references a secret, set that variable up to be pulled in as a secret in GitHub.

4.3. Create Workflow File

Create a GitHub Workflow file to run when a pull request is updated. You can see an example file in the GitHub Actions reference.

Alternatively you could set Hyaline up to be run manually on dispatch.

5. Run MCP Server

Ensure that you have extracted your documentation and placed the resulting data set in a convenient location.

Running the server will vary by client, but the gist of it is you want to have the client run the command hyaline serve mcp --documentation ./path/to/documentation-data-set.db to start a local MCP server listening over stdio.

Please see your client documentation for specific steps.

Next Steps

Read more about Hyaline or visit the CLI reference.