CLI Usage & Evolution

1. The Command Pipeline

The GO-DUCK-CLI operates on basically two commands. The initialization of your system, and the continuous evolution pipeline.

# Command 1: Fresh Creation
# Scaffold an entirely new ecosystem. This generates ALL baseline infrastructure.
go-duck create -o ./MY_APP -c config.yaml -g initial_schema.gdl

# Command 2: Incremental Stateful Update
# Used whenever you modify your GDL (add an entity, drop a column, add a link)
go-duck import-gdl my_new_schema.gdl -o ./MY_APP

2. Persistence Intelligence & the `.go-duck/` Folder

"If I run the generator twice, will it overwrite my database migrations?" No.

The generator maintains a stateful snapshot of every entity it has ever generated inside the hidden .go-duck/ directory at the root of your target project. When you run import-gdl, the code parser literally diffs your new file against the JSON representations in .go-duck/ to intelligently assess the exact Table changes necessary without executing ghost migrations.

3. JHipster-Style "Needles" (Safe Code Injection)

"If I write custom endpoints in `main.go`, will running the generator wipe them out?" No, as long as you use Needles!

The generator utilizes carefully placed specific comments called "needles". For example, inside main.go, you will see markers exactly like // go-duck-needle-add-init-server.

When the generator runs an incremental update, it doesn't arbitrarily overwrite main.go via a template. It opens the existing compiled main.go file on your machine, locates the Needle anchor point via REGEX, and safely inserts the new syntax directly below it.