Makeables badges from the terminal

Build and iterate a badge without opening a browser. The badge JSON file is the state; each command validates the whole design before writing it back. Start with the person below: the real photo, the exact name and the photo treatment.

Start with the person

Before composing, distinguish the user's portrait from a style reference or decorative artwork. An attached mood board, poster or illustration supplies art direction, not the person's photo. If its role is unclear, ask. Reuse a portrait already supplied for this badge; otherwise ask for the photo or its local path. Search a folder when the user asks, and clarify which image to use if several candidates fit. Do not infer the person's identity from a filename.

Resolve the exact display name and image treatment alongside the photo in one short conversational intake. Ask only for missing decisions. A machine username, account name or nickname in agent instructions is not the badge's requested name. Take the mood from the reference when available; ask about the event only if needed.

Offer three plain-language treatments, with a recommendation suited to the reference:

• Original photo: keep its appearance, using only placement and framing. Do not silently add filters or remove its background.
• Editable filters: use the real photo with supported color, monochrome, tint or other native treatments. This needs no image generation.
• Generated image: transform the supplied portrait into an illustration or pixel art, or create separate artwork if that is what the user wants. Clarify the target when ambiguous. Use the images guide for dependencies, external processing and costs.

For a style reference alone, a first reply could be: “Tomo el verde, amarillo y los contornos de stickers como referencia. Pásame tu foto o su ruta y el nombre exacto del badge. ¿La quieres tal cual, con filtros editables o convertida en ilustración? Para este estilo recomiendo conservar tu foto y rodearla de gráficos tipo sticker.” Adapt this to the user's language and omit anything already answered.

Wait for the required photo, exact name and treatment choice or explicit delegation before building the personalized composition. You can inspect tools and prepare authorized dependencies while waiting. Do not replace the person with a mascot, example portrait or provisional name just to produce a first draft. A photo-free badge or fictional participant is fine when the user explicitly requests it. If they delegate the treatment, keep the original photo for the first preview and explain that choice; artistic freedom alone does not authorize paid generation.

Once the inputs are clear, state the direction briefly and design without asking the user to place every layer. Preserve the person's face, framing, pose and proportions. Creating, editing, saving locally and exporting require no account; authentication belongs only to optional public submission.

Loop

makeables styles listmakeables new badge --style vibecode --out badge.jsonmakeables layer list --file badge.jsonmakeables layer set --file badge.json --side front --id event --params '{"text":"SHIP CODE"}'makeables render --file badge.json --side front --out front.png --photo portrait.png --name "Ada Lovelace" --role Speaker --number 12 --overwritemakeables render --file badge.json --side back --out back.png --photo portrait.png --name "Ada Lovelace" --overwrite

After every render, open the PNG and look at it before describing it. Show both faces to the user, ask what to change, then adjust and render again.

What to know

• Faces are 1024 × 1536 units. layer set merges any fields of one layer (text, x, y, w, h, color, size, visible, filter and the rest shown by makeables schema); a layer's id and kind never change. Pass negative numbers with =, as in --rotation=-8.
• makeables layer add --file badge.json --kind text --params '{"text":"SHIP","font":"display","size":96}' adds native text; --kind shape, --kind graphic (an SVG path with viewBox) and --kind qr work the same way.
• A style ties a badge to its event (new badge --style keeps that event's copy and QR). For a person or brand, start from new badge --blank.
• makeables layer add --file badge.json --sticker petdex:boba [--side back] adds a sticker; a local PNG, WebP or SVG path (up to 2 MB; SVG is rasterized) is embedded in the document. Stickers land in the next free corner; move them with layer set --params '{"x":…,"y":…}'. The shared submission package includes embedded stickers and preserves their credits.
• Text layers bound to name, role, number or other fields take their value from --name, --role and --number, not from text.
• Without --photo the render uses a sample portrait and says samplePortrait: true. Never present that as the user's badge.
• Renders are flat print previews. Materials, foil and lighting (satin, prism, chrome) exist only in the browser editor: follow the core guide's surface selection when the user wants to see them.
• makeables validate --file badge.json reports every rule a hand edit broke.

Share a badge

Without a browser, make the complete package from the terminal:

makeables new badge --blank --name "jibaru.dev" --out badge.jsonmakeables badge package --file badge.json --photo portrait.png --name "Ada Lovelace" \  --role Speaker --organization "Analytical Engines" --url https://ada.dev --out badge.makeables.json

--url is what the back QR opens. The package is what kit add and submit accept; never assemble it by hand.

From the live editor, save a complete package with makeables studio save --url "$MAKEABLES_URL" --out badge.makeables.json. It includes the participant, portrait, artwork and both editable faces. Ask whether to iterate or submit to the gallery; after approval, run makeables submit --file badge.makeables.json --yes. Cards, badges and stickers share /submit and admin review. Report the returned status honestly: pending is awaiting review, approved is public. Never recreate the composition just to publish it. Use submit status or retry the same file to recover.

Laminated sleeve

makeables new badge --style laminated --out badge.json starts an editable paper insert with a clear vinyl sleeve. Any badge can use material.holder: "laminated"; "bare" or omission uses the original surface. This is independent of material.surface. In the live editor, choose Background and material → Badge holder → Laminated sleeve. The sleeve has a physical lanyard, clear welded edges and a metal clip. Preview PNG includes the holder; Artwork PNG is the flat design. Cards and stickers do not support this field. Material locks protect the holder.

Print-shop holders and lanyards

A badge and its lanyard are one product. Every badge hangs from a lanyard unless material.holder is "bare" (No lanyard). A badge that names no lanyard gets one derived from its own palette and event; design one that belongs to the badge instead of leaving the default. Every hung holder (laminated, pvc, acrylic) uses the same lanyard and physics; changing the holder type never changes the lanyard. These match the stock a print shop sells, so the preview shows what will be produced:

• material.holder: "pvc": a rigid 10 × 15 cm printed PVC card. material.card.finish is gloss (UV print with clear coat), matte or holographic (iridescent laminate); material.card.punch is round or slot.
• material.holder: "acrylic": the paper insert in a rigid frosted open-face case.
• material.lanyard: ribbon is the stock: polyester (matte sublimated), satin (glossy), woven (jacquard) or nylon (ribbed sheen). print is plain, text (repeated wordmark from text), grid or diagonal, drawn in ink over material.strap. width is 15, 20 or 25 mm. clasp is lobster, trigger, clip (clear strap with press stud, pairs with a slot punch) or ring (split ring, pairs with a round hole). opener: true adds a metal bottle opener.

In the live editor these sit above the preview: holder type, ribbon stock, hook and end. From the CLI, material set changes any of them; lanyard and card merge field by field, so a partial patch keeps the rest of the ribbon:

makeables material set --file badge.json --params '{"holder":"acrylic"}'makeables material set --file badge.json --params '{"lanyard":{"ribbon":"satin","clasp":"trigger","end":"swivel"}}'makeables material set --file badge.json --params '{"strap":"#1e5a2c","lanyard":{"text":"Selva Callao","font":"script"}}'makeables material set --file badge.json --params '{"holder":"bare"}'   # no lanyard

Art direction

The catalog is a reference library, not a template ceiling. Aim for the specificity of Vibecode Fest, She Ships, IA Hackathon and Hack the Andes: a coherent visual idea that changes composition, type, image treatment and material together. Avoid a generic centered photo and a stack of labels unless the user's brief calls for that.

Inspect badge_inspect with section: "catalog" and section: "schema" or use makeables styles list and makeables schema --json. Those live schemas are authoritative for fields, enums and limits. Read a relevant catalog document as an example; do not guess fields.

Choose one strong visual idea from the person's brief. A few possible directions:

• An oversized condensed headline sliced across an asymmetric portrait, small ticket metadata and an acid color field.
• A photographic editorial cover with quiet serif typography, botanical silhouettes and a reverse that reads like a field note.
• A pixel arcade pass with a transformed portrait, modular grid, saturated highlights and a legible terminal-like reverse.
• An Andean expedition credential with bold geographic forms, cropped typography and a material that catches light.

These are prompts for invention, not recipes to repeat. Explain the direction briefly, then compose it rather than asking the user to place every layer.

The full canvas is editable

• Position, size, rotate, hide, duplicate, remove and reorder layers on either face.
• Set typography, scale, weight, alignment, color and name/role bindings.
• Compose vector shapes, SVG paths, graphic patterns, text, portraits, images, QR and effects using the layer kinds exposed by the schema.
• Honor the agreed portrait treatment. Use supported crop, masks and editable filters where that choice calls for them; load the images guide for requested generation.
• Change face backgrounds, material surface and every material/effect parameter the schema supports.
• Build an independent reverse with useful event information and a clear QR, instead of merely copying the front.
• Use badge_edit action replace for a comprehensive new composition. Use patch for iteration; an upsert is a complete layer, and order must include every layer ID once.

Layout changes are freeform inside the current rectangular badge format. Do not promise arbitrary shaders, HTML/CSS layers, new fonts, cut shapes or layer types outside the renderer. Use supported controls creatively. Optional generated artwork can add texture or illustration, while names and important text should remain editable layers.

Make the composition survive different people

Use the event title, artwork and material for the most expressive typography. Give variable identity text enough space to stay readable when the person changes. A composition that works only for a short example name is unfinished.

Default to the complete name binding, with segment: "all" or no segment. first means every word except the last, and last means the last word; these are not cultural given-name/surname fields. Two such layers repeat a single-word name and can squeeze a compound name into the smaller block. Use a split only when the person's requested display name and the intended reuse justify it.

For a reusable name area, prefer a generous width and enough height for multiple lines with fit: "wrap", baseline: "top" and neutral tracking. Set its type size and line height together. Keep the entire area on a predictable contrasting surface, including where extra lines appear. Move decoration or resize the portrait before sacrificing name legibility.

Wrapping can still split an oversized word in the middle. Check wide and hyphenated surnames in the rendered result; a narrower supported typeface or a different size can keep them intact. Give long roles and organizations their own line budget so they do not become tiny after the name is fixed.

shrink only fits the width; it can make text arbitrarily small. spread also distributes characters across the line, which can look broken for a short name. Negative tracking can collide when a long value shrinks. These settings are useful for controlled display text, but are not a substitute for a variable-content layout. Keep full names, accents and compound surnames; do not silently abbreviate them to rescue the composition.

Before presenting a reusable design, render both faces with the actual name, a short single-word name and a long compound name. Include a wide or unbroken name and the intended writing system when relevant. Try realistic long role and organization values too. Use an isolated verification session for these substitutions, and restore its original participant afterward. Do not change the person's shared profile just to run a test.

Inspect the results at the preview's normal size: complete identity, legible type, sensible line breaks, contrast across the whole name area, portrait clearance and unchanged QR space. A schema pass or an oversized PNG does not establish readability. If a case fails, adjust the composition and rerender it; do not call the design universally adaptive after checking only one person.

Constraints that keep the badge usable

The canvas is 1024 × 1536. Array order is paint order. Keep rotated bounds inside the canvas and reserve the top 90 pixels for the physical clip. Both faces need a name binding. The front needs 1–4 portraits. The back needs a role binding and an unrotated, unobstructed, square QR at least 280 pixels wide with contrast of 4.5 or greater. The schema and validator also enforce effect budgets and other bounds.

Read locks before editing. Do not unlock a person's deliberately locked layer without resolving their intent. Selecting a different style resets locks, so do not use style selection to bypass one.

Custom artwork requires both an image layer and imported bytes. A UUID alone is not an image. Preserve the original portrait and its alpha; do not invent a full body from a head-and-shoulders photo.

After composition, pause motion, inspect both faces at actual display size and check the material in motion. Improve obvious hierarchy or crop problems before showing the result. Follow-up requests such as “more chaotic,” “larger type,” or “make the back calmer” should modify the current composition in the same preview.