How to connect Specter to your Shopify store

You want to edit your Shopify blog the way you edit any folder of files — open it in Obsidian, hand it to Claude, run a script across the archive — and have those edits land back on the live store. Before any of that happens, Specter has to be connected. This guide walks the exact OAuth flow, what happens at each step, and what to do when you have more than one store.

What “connecting” actually means on Shopify

Shopify is hosted. Every store lives at your-store.myshopify.com, even when you’ve put a custom domain in front of it, and there’s no self-hosted variant to worry about. That makes the connection model simple: one OAuth flow per store. You don’t generate an API token by hand, you don’t paste a long-lived secret into the app, and there’s no admin password ever involved.

When you connect, Shopify hands Specter an access token scoped only to articles, blogs, and pages — the surface Specter actually operates on. Everything else in the store (orders, customers, products, inventory, payouts, themes, Liquid) stays invisible to the app. The exact scopes and what they grant are covered in What permissions Specter asks for on Shopify.

The connection flow, step by step

1. Enter your store handle on the setup page

Go to the Shopify setup page and type your store handle into the field. The handle is the bit before .myshopify.com — if your store is at acme-coffee.myshopify.com, you type acme-coffee. You can also paste the full acme-coffee.myshopify.com address or even the URL of your admin; the form normalises whatever you give it.

If you have a custom domain (say acmecoffee.com), you still use the myshopify.com handle here. Shopify’s OAuth flow only recognises the canonical handle. You can find it in your Shopify admin under Settings → Domains — the .myshopify.com address is always listed even when you’ve put a custom one in front.

2. Approve Specter in Shopify

Hitting Connect Shopify store redirects you to Shopify’s standard install screen. This is Shopify’s own page, not Specter’s. You’ll see:

• The app name (Specter) and developer
• The exact scopes being requested: read_content and write_content
• A plain-English summary that Specter will be able to read and write your blog posts, articles, blogs, and pages

Read it. If anything looks wrong (an unfamiliar scope, the wrong store at the top of the page), back out. If it looks right, hit Install app. Shopify mints the access token at this moment and redirects you back.

3. Specter opens on your Mac

The redirect lands on a small page that hands the install off to the Specter app via a custom URL scheme. macOS asks once whether to open Specter; allow it. Specter takes over, completes the handshake securely, and stores the access token in the macOS Keychain — not in a config file, not in our servers, not in your browser URL bar.

If Specter isn’t installed yet, this is the point where things stall. Install Specter from the Mac App Store (or build the open-source version from GitHub), then re-run the connection from the setup page.

4. Specter pulls your articles

Once the handshake completes, Specter pulls every article in every blog on the store down to your chosen sync folder. Each article becomes a single .md file with frontmatter holding the title, handle, blog assignment, tags, summary, and SEO fields. From here you’re in normal-folder territory — edit in any tool, preview the diff, push back.

Reinstalling (when the handshake breaks)

If the connection ever ends up in a weird state — token revoked, scopes changed, store renamed — the fix is the same: uninstall and reinstall.

1. In your Shopify admin, go to Settings → Apps and sales channels, find Specter, and click Uninstall. That immediately invalidates the access token on Shopify’s side.
2. In Specter on your Mac, remove the store from the connected-stores list.
3. Run the flow again from the setup page.

This is also what to do if you ever suspect a token has been exposed. There’s no “rotate token” button — uninstall and reinstall is the rotation.

If the handshake fails partway through (Specter doesn’t open, the browser stalls on the redirect, or you see an error after approving in Shopify), the connection-failed troubleshooting guide walks the common causes.

Connecting multiple stores

Plenty of operators run more than one Shopify store — a flagship and a sub-brand, a wholesale storefront, a staging shop. Specter handles this by treating each store as a separate connection with its own access token and its own sync folder.

To add a second store:

1. Open the setup page again.
2. Enter the second store’s handle.
3. Run the OAuth flow — Shopify will ask you to log into whichever store account owns that handle.
4. In Specter, point the new connection at a different folder than your first store.

Don’t try to sync two stores into the same folder. Article handles can collide, and the diff preview gets noisy fast. One store per folder is the rule.

What you’ve actually given Specter

It’s worth being explicit, because Shopify’s install screen flashes past quickly. You’ve given Specter:

• Read and write access to articles, blogs, and pages on this one store
• An access token that lives in your Mac’s Keychain

You have not given Specter access to orders, customers, products, inventory, payouts, themes, Liquid templates, or any other surface of the store. That’s not policy on our side — it’s enforced by Shopify, because those scopes were never requested. The full breakdown is in What permissions Specter asks for on Shopify.

Once you’re connected, the rest of the Specter workflow on Shopify — bulk SEO sweeps, meta description passes, CTA inserts — runs the same way it does on any folder of markdown.