Skip to content

Usage

Requirements

  • Docker must be installed to use the generated docker-compose.yaml files.
  • Go 1.22+ must be installed on your machine to compile the generated services.

Run the tool

ava create

Interactive Prompts

When you run ava create without flags, you will be asked the following questions:

  1. Service Name: The name of your new Go service.
  2. Include PostgreSQL Database?: (y/n) Adds Gorm, migration scripts, and Docker Compose DB setup.
  3. Include Prometheus Metrics?: (y/n) Adds a /metrics endpoint for monitoring.
  4. Include Sentry for error tracking?: (y/n) Adds Sentry integration and middleware.
  5. Include Swagger Documentation?: (y/n) Pre-configures Swagger. Note: You must run swag init manually afterwards.
  6. Service Port: The port your service will listen on (default: 8080).

Non-Interactive Mode (Flags)

For automation, CI/CD, or AI agents, you can use flags to skip the prompts.

ava create -y --name <name> [options]

Available Flags:

  • --yes, -y: Non-interactive mode: skip ALL prompts and use default values for unspecified options.
  • --name, -n <string>: Name of the service.
  • --port, -p <string>: Port to listen on (Default: "8080").
  • --with-db: Include PostgreSQL database.
  • --with-prometheus: Include Prometheus metrics.
  • --with-sentry: Include Sentry error tracking.
  • --with-swagger: Include Swagger documentation.

Examples: 

# Create a minimal service (no prompts, all defaults)
ava create -y --name my-service

# Create a service with DB and Prometheus on port 3000
ava create -y --name auth-service --with-db --with-prometheus --port 3000

You can rerun the generation as many times as needed, each service will be created in a separate folder.

AI / Claude Code Integration

1. Install the Skill:

Run this command once to teach Claude Code how to use Ava-Tool: 

ava install-skill
This installs a custom skill into ~/.claude/skills/ava-create/, allowing Claude to understand ava create commands.

2. Use with Claude:

Now you can ask Claude naturally:

"Create a new user-service with database and metrics"

Claude will understand your intent and execute the correct ava create command.

3. Generated Project Compatibility:

Each generated service includes a .claude/CLAUDE.md file. This file provides instructions for AI agents like Claude Code on how to build, run, test, and understand the project, making it immediately "AI-friendly".

Start a generated service

cd <service-name>
docker-compose up --build

Default endpoints

  • /health: Checks the service availability.
  • /metrics: (Optional) Prometheus metrics.
  • /swagger/*any: (Optional) Swagger API documentation.

Environment variables

  • PORT: Service listening port (default: 8080)
  • GIN_MODE: Gin mode (debug, release, test)
  • SENTRY_DSN: (Optional) Sentry Data Source Name for error tracking.