Short form vs long form (inline --fields vs YAML --from)

You've been mixing them all chapter — the inline --fields "…" form for quick resources, the --from x.yaml form when you needed default: or unique: on a belongs_to. This lesson is the explicit comparison: when each one earns its keep, and which one you reach for in which situation.

The same resource, both ways

Here's a realistic Article resource — title with slug, hero image, formatted body, status with a default — written in both forms side-by-side.

Short form (inline --fields)

$grit generate resource Article \
$  --fields "title:string,slug:slug,cover:string,body:richtext,published:bool"

Long form (YAML)

name: Article
fields:
  - name: title
    type: string
    required: true
  - name: slug
    type: slug
    slug_source: title
  - name: cover
    type: string                # URL heuristic → VARCHAR(500)
  - name: body
    type: richtext
  - name: status
    type: string
    default: draft              # ← only YAML can set defaults
  - name: published
    type: bool
    default: false

$grit generate resource Article --from article.yaml

Both produce the same 8 generated files except the YAML version also sets the database defaults (status = 'draft', published = false) and is committed into the repo — which means the next teammate who pulls can regenerate the resource from scratch by re-running the same command.

What each form supports

YAML field reference — the full spec

Each field entry under fields: accepts seven keys. Most have inline equivalents — two don't:

- name: <field_name>              # camelCase or snake_case — required
  type: <field_type>              # one of the 13 types — required
  required: true|false            # default depends on type (string=true, others=false)
  unique: true|false              # adds DB unique index. Works on belongs_to (1-to-1!).
  default: <value>                # DB default. YAML-only.
  slug_source: <field_name>       # for type: slug — which field to slugify from
  related_model: <ModelName>      # for type: belongs_to or many_to_many — what it points at

That's the whole long-form vocabulary. The inline form compresses the first four into colons (name:type:modifier) and uses the third colon-separated slot for slug_source / related_model:

When to reach for which

Use the short form when…

• You have 1–5 fields and no defaults.
• You're prototyping — the field list will probably change before this resource is real.
• You want the command to fit in a commit message or a chat message to a teammate.
• You're pairing live and reading the spec out loud.

Use the long form (YAML) when…

• You need default values, or you need unique on a belongs_to (one-to-one).
• You have more than 5 fields and the inline string stops fitting on one line.
• You want the resource spec checked into git so anyone can re-generate from scratch later. Drop article.yaml next to grit.config.ts.
• You're generating multiple resources at once and want them all in resources/*.yaml so a script can regenerate the lot.
• The resource spec is reviewed in a PR before code is written — the YAML is the design doc and the source.

The third option — interactive

Don't forget about -i when you genuinely don't know the fields yet:

$grit generate resource Article -i

The CLI walks you through each field one prompt at a time, and at the end it shows you the equivalent --fields string. Great for pairing or for when you're still designing the model in your head.

What's next

You can now write any field shape Grit supports in either form. One last topic for the chapter: grit sync — what to run after you edit a Go struct by hand so the TypeScript types catch up.