Set up with AI and the CLI

You can hand this guide to an AI assistant, or let an AI agent that works with the Shopify CLI set up Transom for you. This page explains what to give it, how the theme's files fit together, and how to keep your live store safe while it works.

You never need this page to use Transom. Everything here can also be done in the theme editor.

Give the guide to an AI assistant

Every page of this guide is also available as plain Markdown, which AI tools read more reliably than a web page.

• The Transom skill: download transom-theme-skill.zip and install it as described in Use Transom with AI tools. Assistants that support skills load the right guide page by themselves.
• One page: select Copy as Markdown at the top of any guide page and paste it into your assistant. Or add .md to the page address, for example https://lintelagency.com/support/transom/sell-more.md.
• The whole guide in one file: https://lintelagency.com/support/transom/llms-full.txt. Give this address to assistants that can read web pages.
• A list of pages: https://lintelagency.com/support/transom/llms.txt lists every page with a one-line summary, for tools that fetch only what they need.
• Every setting id: the Settings reference lists each setting the theme stores, with its type, default and allowed values.

A good first message is: "Read https://lintelagency.com/support/transom/llms-full.txt. I sell [what you sell]. Tell me which preset and product template to use, and which metafields to create."

Work on a copy, never the live theme

Whatever tool makes the changes, follow these rules:

1. In your Shopify admin, go to Online Store > Themes, open the … menu on Transom, and select Duplicate. Work on the copy.
2. Preview the copy before you publish it.
3. Keep a downloaded copy of the theme (… > Download theme file) before large changes.
4. Never share your Shopify password or staff account with an AI tool. The CLI signs in through your browser instead.

Edit the theme with the Shopify CLI

The Shopify CLI downloads a theme to your computer, checks it, and uploads it back. An AI coding agent can run these commands for you.

# Download the duplicated theme (find its ID with: shopify theme list)
shopify theme pull --store your-store.myshopify.com --theme 123456789

# Check the files for errors after editing
shopify theme check

# Upload to the same unpublished copy and get a preview link
shopify theme push --store your-store.myshopify.com --theme 123456789

The CLI refuses to overwrite your published theme unless the command includes --allow-live. Never add it; publish from the admin after you have checked the preview.

Where settings are stored

Each section in a template has a type (which section it is), settings, and optional blocks with a block_order. The Settings reference lists the ids, so an agent can write a valid template without guessing.

Example: switch the home page banner to text below the image and a tall height.

"hero": {
  "type": "image-banner",
  "settings": {
    "text_placement": "below",
    "height": "tall"
  }
}

Images, products, collections, pages and menus are stored by handle. An agent can set a collection by its handle (for example "collection": "living-room"), but images are easier to pick in the theme editor.

Create metafields with the Admin API

Transom reads the metafields listed in Metafields. An agent that can run Admin API GraphQL against your store (through a custom app, the CLI, or an MCP server connected to your store) can create the definitions for you. Check its work under Settings > Custom data.

mutation {
  metafieldDefinitionCreate(definition: {
    name: "Material"
    namespace: "transom"
    key: "material"
    type: "single_line_text_field"
    ownerType: PRODUCT
  }) {
    createdDefinition { id }
    userErrors { field message }
  }
}

Values are written with the metafieldsSet mutation. The reviews.rating and reviews.rating_count fields belong to your review app; let the app fill them.

Two rules an agent must follow, because the theme cannot check them:

• Discounts are not applied by the theme. Every percent in quantity breaks, bundles or cart goals must match an automatic discount created in Shopify. See Sell more.
• Ratings and stock messages must be real. Do not let a tool invent reviews, ratings or low-stock numbers.

A prompt for AI agents

Paste this into an agent that can run the Shopify CLI on your computer. Replace the store address and theme ID.

You are setting up the Transom Shopify theme on my store your-store.myshopify.com.
1. Read https://lintelagency.com/support/transom/llms-full.txt before changing anything.
2. Work only on the unpublished theme 123456789. Never publish, never use --allow-live.
3. Pull it with the Shopify CLI, make the changes, run shopify theme check, and push it back.
4. Use only setting ids from the Settings reference page. Do not invent ids.
5. Do not create discounts, reviews or stock numbers. List any automatic discounts I must create myself.
6. When you finish, give me the preview link and a list of every change.

Help

If a tool gets stuck or a change does not look right in the preview, contact support with your store address and what you asked the tool to do.