Shopify CLI: Complete Guide for App Developers

If you've ever stared at a blank Shopify admin wondering how to bridge the gap between what your store does and what you actually need it to do, you're not alone. Thousands of merchants hit the ceiling of out-of-the-box Shopify functionality every month, and the answer almost always lives in custom app development. The problem is that setting up a professional development environment feels intimidating — especially when you're running a business at the same time.

That's where Shopify CLI comes in. Originally released to simplify the way developers scaffold, test, and deploy Shopify apps and themes, the CLI has matured into an essential toolkit that removes enormous amounts of repetitive setup work. Whether you're a solo merchant who codes on weekends or you're managing a development team for a high-volume store supplying major retail partners, understanding the CLI unlocks faster iteration, fewer errors, and more reliable deployments.

By the end of this guide, you'll know how to install and configure Shopify CLI, scaffold your first app project, connect to a development store, preview themes locally, run app extensions, and deploy production-ready code with confidence. Every section is grounded in practical, specific steps you can follow today — no computer science degree required, and no filler advice about "thinking strategically about your tech stack."

---

What Is Shopify CLI and Why It Matters for Merchants

Shopify CLI is an open-source command-line interface tool maintained by Shopify that lets developers build, preview, and push apps, themes, and custom storefronts directly from a terminal. Before it existed, scaffolding a new Shopify app meant manually copying boilerplate files, configuring OAuth flows by hand, and jumping between multiple documentation pages just to get a local server running. The CLI compresses that entire process into a handful of commands, meaning you spend less time on setup and more time building actual functionality.

For merchants specifically, the CLI matters because it's the foundation underneath virtually every modern Shopify app and theme customisation. When you hire a developer to build a custom loyalty programme, a bespoke checkout extension, or a product bundling tool, they're almost certainly using CLI commands to scaffold, test, and deploy that work. Understanding the basics means you can have more informed conversations with your development team, review their process intelligently, and catch problems before they reach your live store.

The CLI also enforces best practices by design. For example, it automatically handles app authentication using Shopify's OAuth flow rather than requiring developers to write that logic themselves, which reduces the chance of introducing security vulnerabilities. For a store supplying enterprise clients where data integrity and uptime are non-negotiable, that built-in reliability is worth a great deal.

---

Installing Shopify CLI: Step-by-Step Setup

Getting Shopify CLI running on your machine starts with Node.js, which must be version 18 or higher for the current CLI version to function correctly. You can check your existing Node version by running node -v in your terminal — if you're below version 18, download the latest LTS release from nodejs.org before proceeding. Once Node is confirmed, install the CLI globally using npm with the command npm install -g @shopify/cli, which typically completes in under two minutes on a standard broadband connection.

After installation, run shopify version to confirm everything installed correctly — you should see a version number printed back to you, such as 3.x.x. From there, authenticate with your Shopify Partner account by running shopify auth login, which opens a browser window and prompts you to log in through Shopify's secure OAuth flow. You don't need to store any passwords locally; the CLI handles token management automatically and stores credentials securely on your machine.

One practical tip that saves time later: if you're working across multiple Partner accounts — for instance, managing a development store separately from your live merchant account — use the --store flag when running commands to specify exactly which store you're targeting. Running commands against the wrong store is a surprisingly common mistake, and it can cause real confusion when you're debugging theme changes or app behaviour. Labelling your terminal sessions clearly is a small habit that prevents significant headaches.

---

Scaffolding Your First Shopify App Project

Once the CLI is installed and authenticated, creating a new app project takes a single command: shopify app init. The CLI will prompt you to name your app, choose a template (Remix is currently the recommended framework), and select your preferred language — TypeScript is generally the better choice for larger projects because it catches type errors before they reach production. Within about thirty seconds, you have a fully structured project directory with routing, authentication middleware, and a working local development server pre-configured.

The generated project includes a shopify.app.toml configuration file, which is where you define your app's scopes, redirect URLs, and extension configurations in a single declarative file. This matters because prior to the TOML-based configuration system, developers had to manage these settings through the Partner Dashboard UI and then manually keep their local configuration in sync — a process prone to drift and errors. Now, your configuration lives in version control alongside your code, making it auditable and reproducible across team members.

To connect your scaffolded app to a development store, run shopify app dev from your project directory. The CLI automatically creates a tunnel using Cloudflare's tunnelling service, generates a unique HTTPS URL for your local server, and installs your app on the selected development store — all without you touching a single network configuration. You'll see live logs in your terminal as the app runs, making it straightforward to identify issues as they occur rather than hunting through server logs after the fact.

---

Working with Theme Development and Local Previews

Shopify CLI includes a powerful theme development workflow that separates it from simply editing theme files through the online code editor. Running shopify theme dev in a theme directory spins up a local server that proxies your development store, hot-reloads changes as you save files, and lets you test responsive layouts and JavaScript behaviour without pushing anything to your live store. For merchants making significant theme changes — restructuring a product page layout, for example, or integrating a custom section schema — this local environment is invaluable.

The CLI also supports shopify theme pull and shopify theme push commands that synchronise theme files between your local machine and your Shopify store. A practical workflow many development teams use is to maintain a staging theme on the store, run shopify theme pull --theme [theme-id] to get the latest version locally, make and test changes, then push back to staging for client review before going live. This keeps your production theme completely untouched until you're confident the changes are correct.

One specific use case worth highlighting: if you're running a Shopify store that sells into retail or B2B channels and you need collection pages to behave differently for different customer segments, theme development via CLI lets you iterate on conditional Liquid logic locally and verify behaviour before it affects any live customer session. That kind of precision matters when your store's reputation rests on a professional purchasing experience for trade clients.

---

Building and Testing App Extensions

App extensions are modular pieces of functionality that extend Shopify's native UI — think checkout extensions that add a gift message field, product page blocks that display custom metafields, or admin action extensions that let your team trigger fulfilment workflows. Running shopify app generate extension presents a menu of extension types and scaffolds the appropriate boilerplate automatically, saving significant time compared to writing the file structure from scratch.

Once your extension is generated, the shopify app dev command previews it live in your development store using the Shopify App Bridge integration, meaning you can see exactly how your checkout extension renders inside the actual Shopify checkout UI, not a simulated environment. This accuracy reduces the number of surprises that appear when you eventually deploy to production. For checkout extensions in particular, where visual inconsistencies can erode customer trust and reduce conversion, testing in a faithful environment is critical.

The SaltAI Agent for Shopify integrates with your existing Shopify workflow as a deployed app extension, which means it benefits from exactly this kind of structured development and testing process. Using the CLI to build and validate extensions locally before deployment is the standard professional approach, and it's why well-built apps behave predictably across different store configurations and themes.

---

Deploying to Production: Best Practices

When your app or theme changes are tested and ready, deployment via CLI is significantly more reliable than manual file uploads. For apps, shopify app deploy pushes your extension code to Shopify's infrastructure, creates a new app version, and requires you to explicitly release that version — giving you a moment to review what's going live before it becomes active for users. This two-step deploy-then-release model is a deliberate safety mechanism that many developers appreciate after experiencing the consequences of an accidental immediate deployment.

For themes, shopify theme push with the --publish flag makes your theme live, but the safer practice is to push without that flag first, preview the unpublished theme using Shopify's theme preview URL, and only publish once you've confirmed everything looks correct across desktop and mobile. Many teams also use shopify theme check before pushing, which runs a linter against your Liquid templates and flags deprecated syntax, missing required files, or performance issues like render-blocking scripts. Catching these issues locally is far better than discovering them via a customer complaint.

Version control integration deserves specific mention: pairing CLI commands with a Git workflow — committing changes, branching for features, tagging releases — gives you a complete history of every deployment. If a theme update breaks something, you can identify exactly which commit introduced the problem and roll back with confidence. For stores processing significant daily order volumes, that kind of operational discipline is not optional.

---

Conclusion

Shopify CLI transforms app and theme development from a fragmented, error-prone process into a structured, repeatable workflow. The key takeaways from this guide are straightforward: install the CLI with Node 18 or higher, use shopify app init to scaffold projects correctly from the start, lean on shopify theme dev for safe local theme iteration, and always follow the deploy-then-review-then-release pattern for production changes. Every one of these practices reduces risk and saves time — two resources that matter enormously when you're running a real business with real customers.

The CLI is a tool for building. What you build with it — whether that's a custom checkout experience, a B2B product configurator, or a smarter inventory workflow — determines the actual value it delivers to your store. Start with the fundamentals in this guide, build systematically, and you'll find that the distance between your store's current capabilities and what you actually need it to do is far shorter than it looks.

Try SaltAI Agent for Shopify free at saltai.app — no credit card required.