Tradecraft CLI

The tradecraft command starts, splices, and updates Shopify theme projects built on Groupthought's themes: Pipeline, Story, and Analog. It also installs as tdc.

A Tradecraft project keeps a store's theme, its settings, and its custom code in Git. The CLI starts the project from a theme release, carries the store's custom code onto it, and moves it to new releases later without losing your changes.

Requirements

• A Tradecraft account, for everything except a comparison of two zips. Access is by invitation during the beta.
• Node.js 22.12 or later, Git, and pnpm.
• Access to the store in Shopify: a staff account, or a Theme Access password.

Install

npm install -g tradecraft-cli
tradecraft --help

Start a project

tradecraft login
tradecraft new

login signs in through your browser. new asks for the store, the theme, and the environments, then creates the project folder and installs it. Commit the project before the next step, so the splice shows up as its own diff:

cd <project>
git init
git add -A
git commit -m "Start the project"
tradecraft splice

splice pulls the store's live theme and compares it with the release it came from. The project's agent skills, in .agents/skills/, then help you or an AI agent such as Claude Code or Codex rebuild the custom code on the new theme. To preview the theme on a development theme in the store, run pnpm dev:<environment>.

Try it without an account

splice can compare a customized theme with its original release from two zips, with no account, project, or store:

tradecraft splice --original pipeline-8.2.0.zip --current live-theme.zip

It writes the comparison to splice/live-theme/ and adds the splice-audit skill to .agents/skills/, so an AI agent such as Claude Code or Codex can turn the comparison into a to-do list. The other skills, such as the page compiler and the rebuild workflow, come with a Tradecraft account: a signed-in tradecraft new or tradecraft update installs them.

Commands

| Command | Use | |---|---| | tradecraft login | Sign in to your Tradecraft account | | tradecraft new | Start a project from a store | | tradecraft splice | Compare the store's theme with its release, to carry its custom code over. Works from two zips without an account | | tradecraft add | Add an environment, which names a store, and pull its settings | | tradecraft update | Update the theme and its packages to a newer release | | tradecraft adopt | Take a package into the project as editable source | | tradecraft api graphql | Query your store in Assembly | | tradecraft status | Show the project and check the setup |

Run tradecraft help <command> for a command's options. The commands that build, preview, and deploy a theme are the project's own scripts, such as pnpm dev:production.

Keep a project current

• tradecraft update moves the project to a newer theme release. Your changes to the theme merge with the release's changes, and Git shows any conflicts. It also brings the newest agent skills, even when the theme has no new release. Start from a clean Git tree. --dry-run shows the plan without changing anything.
• tradecraft adopt ui makes a package editable in packages/. Later updates merge with your changes to it instead of replacing it.
• tradecraft add environment staging --store example-staging.myshopify.com adds a store to the project.

Use the store's Assembly data

tradecraft login --store example.myshopify.com signs in to that store's Assembly data, such as its photo library. The browser shows the store, and you approve it. After that, tradecraft api reads the store from any folder. To change the store, run tradecraft login --store again.

Inside a project, tradecraft login takes the store from the project's shopify.theme.toml, and the login is for that project only. Every other folder uses the login you made outside a project.

tradecraft api graphql -f query='{ shop { name domain cliAccess } }'

Before each request the CLI prints the store and its access level, such as example.myshopify.com · read. The project's assembly-api skill shows Claude Code and Codex how to query it.

Run it from an agent or CI

Every command is a wizard. Each question also has a flag, and --yes accepts every default, so a command can run without a person. --json prints a report that a program can read. SHOPIFY_CLI_THEME_TOKEN gives a Theme Access password instead of a Shopify sign-in.

Exit codes: 0 success, 1 a usage error or a failure, 130 cancelled.

Files on your computer

• ~/.config/tradecraft/session.json holds your sign-in. Only your user can read it.
• ~/.config/tradecraft/projects/ holds each project's own sign-in. Nothing goes in the project folder.
• ~/.cache/tradecraft/ holds a partial copy of the theme releases.

XDG_CONFIG_HOME and XDG_CACHE_HOME move them.

License and support

The CLI, the themes, and the packages it installs are under the Tradecraft License, in LICENSE.md and at https://assembly.groupthought.com/license. Using Tradecraft also means accepting the Terms of Service and the Privacy Policy.

For help, email [email protected].