Table of Contents

• Quickstart
  • Marketplace Workflow (Recommended)
    • 1. Search for Templates
    • 2. Install a Gpack
    • 3. Generate Code
    • 4. Verify Installation
  • Local Templates (Advanced)
    • 1. Initialize Project Structure
    • 2. Create Template
    • 3. Generate
  • Marketplace vs Local Templates
  • Troubleshooting
    • First-time Setup Issues
    • Template Not Found
    • Generation Errors

Quickstart

Marketplace Workflow (Recommended)

The fastest way to get started with ggen is using marketplace gpacks - pre-built, tested template collections.

1. Search for Templates

# Search for CLI subcommand templates
ggen search rust cli

# Output:
# ID                                    LATEST     KIND       TAGS
# io.ggen.rust.cli-subcommand           0.2.1      template   rust, cli, clap
# io.ggen.rust.api-endpoint             0.1.5      template   rust, api, axum

2. Install a Gpack

# Install the latest version
ggen add io.ggen.rust.cli-subcommand

# Or install specific version
ggen add io.ggen.rust.cli-subcommand@0.2.0

3. Generate Code

# Use the installed gpack template
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello description="Print a greeting"

4. Verify Installation

# List installed gpacks
ggen packs

# Show template details
ggen show io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl

Result:

src/cmds/hello.rs

Local Templates (Advanced)

For custom templates or when you need full control over the generation process:

1. Initialize Project Structure

mkdir -p templates/cli/subcommand

2. Create Template

Create templates/cli/subcommand/rust.tmpl:

---
to: src/cmds/{{ slug }}.rs
vars: { cmd: hello, summary: "Print a greeting", seed: cosmos }
rdf:
  - "graphs/cli.ttl"              # Local RDF file
shape:
  - "graphs/shapes/cli.shacl.ttl" # Local SHACL shapes
sparql:
  vars:
    - name: slug
      query: |
        PREFIX cli: <urn:ggen:cli#>
        SELECT ?slug WHERE { ?c a cli:Command ; cli:slug ?slug } LIMIT 1
determinism: { seed: "{{ seed }}" }
---
pub fn {{ slug }}(name:&str){ println!("hello {}", name); }

3. Generate

ggen gen cli subcommand --vars cmd=hello summary="Print a greeting"

Marketplace vs Local Templates

Troubleshooting

First-time Setup Issues

# If ggen command not found after installation
which ggen
# Should show path to ggen binary

# If marketplace search fails
ggen search --help
# Check network connectivity and registry access

Template Not Found

# Check if gpack is installed
ggen packs

# Reinstall if missing
ggen add io.ggen.rust.cli-subcommand

# Verify template path
ggen show io.ggen.rust.cli-subcommand

Generation Errors

# Use dry run to preview
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello --dry

# Check variable requirements
ggen show io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl