Getting Started with Goat

Goat is a modern code generator and automation environment that helps you rapidly develop complete applications without losing control over the code.

Instead of treating generation as a one-time project scaffolding process, Goat lets you safely and selectively introduce subsequent changes into an existing application. Generated code remains regular source code — you can modify, extend, and commit it manually just like the rest of the project.

You can create a new project using:

goat init ./my-project \
  --name my-project \
  --git-repo https://github.com/your-user/my-project.git

The command initializes an application based on a prepared Git repository and creates a ready starting point for further work.

The default Goat starter provides an application based on Go and Angular, but the generator mechanism itself is flexible and can be adapted to the architecture and conventions of a specific project.

Why Goat?

A large part of business application development is repetitive: data models, DTOs, DAOs, forms, endpoints, validation, migrations, and basic CRUD operations.

Goat automates this layer, allowing you to focus on what truly differentiates the application:

  • business logic,
  • security,
  • interface quality,
  • integrations,
  • performance,
  • features that deliver value to users.

At the same time, a shared application model helps maintain consistency between the frontend and backend. Based on it, entities, DTOs, DAOs, API endpoints, and their corresponding interface elements can be generated, among other things.

The generator is meant to accelerate work, not lock the user into a prescribed generation model.

Therefore, you can use Goat wherever it provides real time savings, and then freely continue developing the generated code manually.

Safe Script Execution

One of Goat's main principles is isolating automation from the host system.

Typical development tools often run installation scripts directly on the developer's machine. For example, npm install may execute code originating from installed dependencies.

Goat reduces the surface area of this risk.

Scripts run by Goat operate in an isolated environment and can only access resources that have been explicitly made available to them. In a typical scenario, this primarily means the current project directory.

As a result, automation:

  • does not receive unrestricted access to the host system,
  • should not modify files outside the current project,
  • can run tools such as Node.js, npm, or PostgreSQL without installing them locally,
  • maintains a similar execution environment across different operating systems.

Docker provides the isolation and portability layer here, while Goat offers a convenient way to define and run entire development workflows.

A Generator That Adapts to the Project

Goat does not assume that generated code should remain untouched.

You can freely edit the code manually. The generator should, however, introduce changes as locally and deliberately as possible, rather than overwriting entire application modules every time.

This makes it possible to combine two ways of working:

generating what is repetitive and manually developing what is specific to the project.

This approach is particularly important in larger projects, where the generator must coexist with code developed by programmers over many months or years.

Goat and AI

The constrained, declarative project model also works well with AI tools.

Instead of analyzing a large part of the repository, the model can often work with a much smaller description of the domain and generator configuration.

This makes it possible to:

  • limit the amount of code sent to the model,
  • reduce the cost of using AI,
  • shorten project analysis time,
  • limit the number of places AI needs to modify,
  • increase the predictability of generated changes.

AI can therefore primarily help modify the application model and intent, while Goat consistently translates those changes into code.

This does not mean, however, that work must be done exclusively at the model level. If a specific change is easier to make directly in code, the generated files can be edited normally.

Who this project is for

Choose Goat when you are building an application based on structured data, forms, APIs, and an administration panel, and want to move quickly from a domain model to a working system.

The basic workflow is simple:

  1. create a project using goat init,
  2. describe entities and relationships in herd/_model.goat,
  3. run the generator,
  4. Goat creates or updates the related application components,
  5. extend the generated code where custom logic is needed.

Goat works particularly well where an application contains a lot of repetitive infrastructure while also requiring custom business logic and further manual development.

Requirements

  • Docker,
  • Go — if you run go run ./scripts ... commands directly on the host,
  • Git and standard shell tools.

You do not need to install PostgreSQL or Node.js directly on your computer. The herd/*.goat scripts can run the required tools and services inside containers.

Quick start

1. Create a project

In a new directory, run:

goat init ./my-project \
  --name my-project \
  --git-repo https://github.com/your-user/my-project.git

The command creates a new project based on a prepared Git repository.

This immediately gives you a complete project structure, including:

  • an example application model,
  • generator configuration,
  • .goat scripts,
  • sample fixture data,
  • documentation tailored to the current project version,
  • a backend and frontend ready for further development.

goat init is therefore used not only to create an empty project, but to prepare a complete starter environment that can be immediately run, analyzed, and modified.

2. Configure the environment

Fill in the local file:

.env

Do not put real secrets in the repository.

Values such as database passwords or GOAT_JWT_SECRET should remain local or be provided by the secret management system for the relevant environment.

3. Start the development environment

Run:

goat run:script --path=herd/dev.goat

If you are using the project's source tools directly, you can also use:

go run ./scripts run:script --path=herd/dev.goat

The script prepares a complete local development environment.

During the first run, Goat, among other things:

  • starts the required services,
  • generates the application,
  • prepares the database,
  • runs migrations,
  • builds the required project components,
  • loads data from herd/fixture.goat,
  • starts the backend and frontend.

4. Open the application

Once initialization is complete, the application is available at:

http://localhost:8080

Additional services:

  • pgAdmin: http://localhost:5050,
  • PostgreSQL: localhost:5433.

Thanks to the fixtures provided by the project, from the very first run you can see not only a working application, but also sample data and documentation corresponding to the currently used version of Goat.

What next?

After starting the project, you will most often work in the following cycle:

change the model or code
        ↓
goat re
        ↓
review changes
        ↓
manual refinement
        ↓
tests

The application model is located in:

herd/_model.goat

After changing it, you can regenerate the code:

goat re

Then review the result:

git diff

and run the tests:

goat run:script --path=herd/test.goat

Next steps

  • Learn about the [project architecture](/doc/en/project-architecture).
  • Configure your [local environment](/doc/en/environment-configuration).
  • See how to modify the [data model and generate code](/doc/en/data-model-and-code-generation).
  • Learn about the [local development workflow](/doc/en/local-development).
  • Check [testing and available commands](/doc/en/testing-and-commands).