05 Shopify CLI

Di 02 Bikin Theme Baru dari Skeleton dan 03 Kustomisasi Theme Milik Merchant kita udah pakai beberapa perintah CLI tanpa banyak penjelasan. Sekarang kita bongkar alatnya sampai ke dalam.

Shopify CLI itu alat baris perintah buat bikin app dan theme Shopify. Buat theme, dia bisa ngelakuin ini semua:

Preview, tes, dan bagiin perubahan dengan aman lewat development theme.
Hot reload perubahan CSS dan section, atau auto-refresh halaman tiap file berubah.
Bikin theme baru.
Push dan publish theme dari terminal.
Kerja di banyak theme sekaligus pakai environments.
Jalanin Theme Check buat ngecek kualitas kode.

CLI ini juga bisa dipakai buat app dan Hydrogen, tapi buku ini cuma bahas bagian theme-nya. Cara install-nya ada di 02 Bikin Theme Baru dari Skeleton > Install Shopify CLI.

Development Theme

Ini konsep paling penting di CLI, jadi kita bahas duluan.

Development theme itu theme sementara yang tersembunyi, nyambung ke toko yang lagi kamu pakai buat ngoding. Waktu kamu jalanin shopify theme dev, CLI upload theme lokalmu ke toko sebagai development theme, dan kamu bisa pakai data asli toko itu buat ngetes.

Sifat-sifatnya:

Bisa dipakai di toko biasa maupun dev store.
Gak ngabisin jatah theme toko (tiap toko punya batas jumlah theme di library-nya).
Dihapus otomatis setelah 7 hari gak aktif.
Dihapus kalau kamu jalanin shopify auth logout.

Yang bisa kamu lakuin sama development theme:

Lihat perubahan secara langsung waktu ngoding lokal.
Buka dan utak-atik lewat theme editor di Shopify admin.
Bagiin preview berpassword ke developer lain.

Karena sifatnya sementara, kalau butuh link preview yang tetap hidup setelah logout, push dulu ke theme yang belum tayang pakai shopify theme push --unpublished.

Daftar Perintahnya

Semua perintah berawalan shopify theme. Ini daftar lengkapnya, dikelompokin biar gampang diinget:

Bikin dan nyiapin:

init, nyalin repository Git (bawaannya Skeleton theme) ke komputermu sebagai titik awal.
package, ngebungkus theme lokalmu jadi file ZIP yang bisa di-upload ke Shopify. Ini cara distribusi ZIP yang disebut di 01 Apa itu Theme Shopify > Cara Nyebarin Theme.

Ngoding dan preview:

dev, upload theme sebagai development theme (atau ke theme tertentu) biar bisa di-preview.
preview, nerapin file JSON overrides ke sebuah theme dan bikin preview-nya, tanpa ngubah file apapun secara permanen. Bahasannya di bawah.
open, ngasih link buat preview theme tertentu.
console, nyalain Liquid REPL, alias terminal interaktif buat ngetik kode Liquid dan langsung lihat hasilnya. Berguna banget buat nyoba-nyoba filter atau object tanpa harus ngedit file.
profile, ngukur performa Liquid di sebuah halaman, buat nyari bagian yang lambat.

Sinkronisasi ke Shopify:

pull, download file theme dari Shopify.
push, upload file theme lokal ke Shopify, nimpa versi remote kalau disebut.
share, upload theme sebagai theme baru yang belum tayang di library. Mirip push --unpublished.
publish, mem-publish theme yang belum tayang dari library.
metafields pull, ngambil definisi metafield dari Shopify admin, biar editor lokalmu bisa auto-complete nama metafield.

Ngatur theme di toko:

list, daftar semua theme di toko beserta ID dan statusnya.
info, info soal environment theme-mu, termasuk toko mana yang lagi nyambung.
rename, ganti nama theme di toko.
duplicate, duplikat theme. Theme lokal harus di-push dulu sebelum bisa diduplikat.
delete, hapus theme dari toko.

Kualitas kode:

check, jalanin Theme Check buat nganalisis kode theme. Bahasannya di 65 Theme Check Pengenalan, Konfigurasi, Commands.
language-server, nyalain Liquid Language Server buat integrasi editor. Bahasannya di 07 Tools Lokal VS Code Extension, Prettier, LiquidDoc.

Referensi lengkap tiap perintah beserta flag-nya ada di Shopify CLI theme command reference.

Autentikasi dan Akses Toko

Ada tiga cara CLI bisa masuk ke toko:

Ini cara bawaan. Akun yang bisa dipakai:

Collaborator account dengan izin Manage themes.
Staff account dengan izin Themes.
Akun pemilik toko.

Kamu gak perlu login secara eksplisit. Jalanin aja perintah yang butuh akses toko, nanti kamu diminta login. Buat ganti akun:

shopify auth logout

Perintah berikutnya yang butuh autentikasi bakal minta login lagi, dan kamu bisa masukin akun yang beda. Ingat, logout juga ngehapus development theme-mu.

2. Password Theme Access

Password dari app Theme Access. Dipakai lewat flag --password di tiap perintah:

shopify theme dev --store my-store --password shptka_xxxxxxxx

Kalau kamu jalanin perintah tanpa --password, CLI balik nyoba pakai akun Shopify-mu. Jadi password ini gak “nempel”, harus disebut terus. Kalau males ngetik terus, pakai environments yang dibahas di bawah.

3. Token Custom App

Kamu juga bisa pakai access token dari custom app, dikirim lewat flag --password juga. Syaratnya app-nya punya access scope read_themes dan write_themes. Kalau mau hot reload jalan, tambahin scope unauthenticated_read_content dan kirim token-nya lewat environment variable, bukan flag.

Ini jarang dipakai buat theme, biasanya buat integrasi khusus.

Nyambung ke Toko

Pertama kali jalanin perintah yang butuh toko, sebutin tokonya pakai --store:

shopify theme dev --store my-store

Toko itu bakal diinget buat perintah-perintah berikutnya sampai kamu nyebut --store lagi dengan nilai baru. Cek lagi nyambung ke mana:

shopify theme info

Outputnya kurang lebih:

THEME CONFIGURATION
-----------------------
Store   my-store.myshopify.com
...

Struktur Folder yang Diharapkan

Beberapa perintah kaya shopify theme dev cuma jalan kalau foldermu ngikutin struktur theme standar yang dibahas di 01 Apa itu Theme Shopify > Struktur Foldernya:

└── project
    ├── assets
    ├── blocks
    ├── config
    ├── layout
    ├── locales
    ├── sections
    ├── snippets
    └── templates
        └── customers

Struktur ini mewakili theme yang gak butuh proses build, atau theme yang udah selesai di-build. Kalau kamu pakai alat build (misalnya SCSS yang dikompilasi jadi CSS), kamu harus jalanin perintah CLI dari folder hasil build-nya, bukan folder sumbernya. Bahasan file transformation ada di 54 Best Practices Umum.

❌ salah, jalanin CLI dari folder sumber yang belum di-build

cd my-theme/src
shopify theme dev

✅ benar, jalanin dari folder hasil build yang strukturnya standar

cd my-theme/dist
shopify theme dev

Ngecualiin File

Kalau di repository ada file yang gak mau disentuh CLI (misalnya file catatan, file rahasia, atau file mentah sebelum di-build), tambahin ke file .shopifyignore di root theme. Formatnya:

Nama file biasa: templates/product.temp.json
Wildcard: config/*_secret.json, *.jpg
Regular expression: /\.(txt|gif|bat)$/

Contoh isi .shopifyignore:

templates/product.temp.json
config/*_secret.json
/\.(txt|gif|bat)$/

Selain itu, waktu push atau pull kamu juga bisa ngecualiin file pakai flag --ignore. Kalau dua-duanya dipakai, isi .shopifyignore dan --ignore sama-sama dihormatin.

Environments

Kebanyakan konfigurasi perintah (theme mana, toko mana, password apa) dikirim lewat flag. Kalau tiap perintah harus nulis 4 flag, capek. Makanya ada environments: sekumpulan konfigurasi yang dikasih nama, terus dipanggil pakai satu flag --environment.

Kapan butuh ini:

Kamu sering gonta-ganti dev store.
Kamu akses banyak toko pakai password Theme Access yang beda-beda.
Kamu mau deploy ke development, staging, dan production dari satu project.

1. Bikin Environment

Environment diatur per repository theme lewat file shopify.theme.toml:

Bikin file shopify.theme.toml di root project.
Buat tiap environment, tambahin judul tabel dengan format [environments.NAMA].
Di bawahnya, tulis pasangan kunci-nilai buat flag yang mau dipakai.

Contoh:

[environments.env1]
theme = "123456789012"
store = "my-store"
password = "shptka_123456"
ignore = "sections/header.liquid"
 
[environments.env2]
store = "another-store"
path = "./dist"
ignore = ["sections/announcement-bar.liquid", "sections/header.liquid"]
output = "json"
live = true
allow-live = true

Kamu bisa set flag apapun di sini, kecuali environment, path, dan verbose yang diabaikan. Buat flag boolean, tulis true.

Satu peringatan: beberapa flag punya arti beda tergantung perintahnya, misalnya force. Kalau force kamu taruh di environment, terus kamu jalanin delete pakai environment itu, theme-nya langsung dihapus tanpa konfirmasi. Jadi hati-hati naruh flag yang “berbahaya” di environment.

❌ bahaya, force nempel di environment dan bakal bikin delete gak nanya

[environments.prod]
store = "my-store"
force = true

✅ aman, force disebut manual cuma waktu emang dibutuhin

[environments.prod]
store = "my-store"

2. Pakai Environment

shopify theme dev --environment env1
 
# atau pakai alias pendeknya
shopify theme dev -e env1

CLI bakal nampilin flag apa aja yang dipakai dari environment itu:

╭─ info ─────────────────────────────────────────────────╮
│  Using applicable flags from env1 environment:         │
│    • store: my-store                                   │
│    • password: *******456                              │
│    • ignore = "sections/header.liquid"                 │
╰────────────────────────────────────────────────────────╯

3. Environment Default

Males ngetik --environment terus? Bikin environment bernama [environments.default], dan semua perintah theme bakal otomatis pakai itu. Kamu tetap bisa nimpanya dengan nyebut --environment lain kapan aja.

4. Urutan Prioritas

Kalau nilai yang sama ada di beberapa tempat, urutan menangnya:

Flag di perintah (paling kuat).
Environment variable (kaya SHOPIFY_FLAG_STORE).
Setting di shopify.theme.toml (paling lemah).

Jadi kalau kamu nulis --store di perintah, itu yang dipakai, bukan yang di environment:

shopify theme dev --environment env1 --store my-new-store --password shptka_102938

Outputnya cuma nunjukin ignore yang diambil dari environment, karena store dan password udah ditimpa flag.

Aturan lainnya: flag yang gak berlaku buat perintah yang lagi dijalanin bakal diabaikan (bukan error), tapi kalau tipe datanya salah atau ada flag yang saling bertentangan, bakal error.

5. Banyak Environment Sekaligus

Beberapa perintah bisa dijalanin ke banyak environment sekaligus: check, delete, info, list, publish, pull, push, rename, dan share.

shopify theme delete --environment env1 --environment env2 --development

Bedanya: waktu pakai banyak environment, CLI gak bakal nanya info yang kurang. Semua flag wajib harus lengkap di perintah atau di shopify.theme.toml. Kalau ada yang kurang, environment itu dilewati dengan peringatan. Kalau perintahnya punya flag --force, bakal ada konfirmasi dulu; kalau nggak, langsung jalan.

theme preview dan File Overrides

Perintah shopify theme preview punya flag --overrides yang nerima path ke file JSON. Isinya perubahan virtual yang ditumpuk di atas theme remote, cuma di memori, gak ada file yang diubah permanen di Shopify.

Ini berguna buat nyoba “gimana kalau bagian ini diganti gini” tanpa nyentuh theme aslinya. Strukturnya:

{
  "metadata": {
    "version": "0.1.0"
  },
  "theme_changes": { ... }
}

Di dalam theme_changes, tiap kunci itu path file theme, dan isinya salah satu dari tiga operasi:

1. source, Ganti Seluruh Isi File

{
  "theme_changes": {
    "templates/product.liquid": {
      "source": "<div>{{ product.title }}</div>"
    }
  }
}

Kalau file-nya belum ada, bakal dibikin sebagai file virtual yang bisa dirujuk file lain. Misalnya kamu bikin snippet virtual pakai source, terus di override lain kamu panggil pakai {% render 'my-snippet' %}.

2. merge, Gabungin ke File JSON

Buat file JSON kaya settings dan locale, merge nggabungin objek yang kamu kasih ke file yang ada (deep merge):

{
  "theme_changes": {
    "templates/index.json": {
      "merge": {
        "current": {
          "product_image_size": "large"
        }
      }
    }
  }
}

3. diffs, Tempel Patch

Nerapin diff ke satu file. Format diff biasa maupun diff -u / git diff diterima dan dideteksi otomatis:

{
  "theme_changes": {
    "templates/price.liquid": {
      "diffs": "3a4,6\n {% render 'sale-badge' %}\n"
    }
  }
}

Ada juga diffs di level atas buat nempel seluruh output git diff sekaligus. CLI bakal nyari path file dari baris +++ b/<path>. Jadi kamu bisa git diff dari Dawn atau theme fork manapun dan langsung kirim:

{
  "theme_changes": {
    "diffs": "diff --git a/templates/index.json b/templates/index.json\n..."
  }
}

Tapi diffs level atas gak bisa dicampur sama diffs per file dalam satu theme_changes.

Shopify CLI di CI/CD

Kalau kamu mau theme-nya di-push otomatis tiap ada kode masuk ke branch tertentu, integrasikan CLI ke pipeline CI/CD. Syaratnya Shopify CLI 3.20 ke atas.

1. Dapetin Password Theme Access

Buat tiap toko yang mau diakses dari pipeline, kamu butuh password dari app Theme Access. Caranya di 04 Dev Store, Akun Kolaborator, dan Theme Access > Theme Access. Pipeline gak bisa login interaktif, makanya butuh password ini.

2. Pasang di Pipeline

Langkah di pipeline harus:

Nyediain environment variable ini: 2. SHOPIFY_CLI_THEME_TOKEN (wajib), password Theme Access-nya. 3. SHOPIFY_FLAG_STORE (wajib), tokonya. 4. SHOPIFY_FLAG_FORCE (opsional), isi 1 buat matiin prompt interaktif. Pakai ini kalau langkah pipeline-mu sering timeout karena nunggu jawaban yang gak pernah datang.
Setup Node.js.
Install Shopify CLI global.
Jalanin perintah CLI-nya.

Lindungi password-nya dengan nyimpen sebagai secret dan pastiin gak kecetak di log.

Contoh GitHub Actions yang push theme tiap ada push ke branch main:

name: Theme deploy
 
on: [push]
 
jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
 
      - name: Install Shopify CLI
        run: npm install -g @shopify/cli
 
      - name: Upload theme
        run: |
          shopify theme push \
            --json \
            --theme your-theme-name-or-id \
            --store ${{ secrets.SHOPIFY_FLAG_STORE }} \
            --password ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}

Perhatiin --json: itu biar outputnya berbentuk JSON yang gampang dibaca mesin, bukan tampilan warna-warni buat manusia.

Liquid Language Server

CLI juga nyediain Language Server buat Liquid. Ini standar (Language Server Protocol) yang bikin fitur editor (auto-complete, dokumentasi, formatting, deteksi error, navigasi kode) bisa dipakai di semua code editor dari satu program yang sama, gak perlu bikin plugin khusus per editor.

Nyalainnya:

shopify theme language-server

Tiap editor punya cara sendiri buat nyambung ke language server, tapi prinsipnya sama: ngasih tau editor cara nyalain server-nya. Contoh implementasinya ada di wiki Theme Tools. Kalau kamu pakai VS Code, gak perlu repot, extension resminya udah ngurus ini. Bahasannya di 07 Tools Lokal VS Code Extension, Prettier, LiquidDoc.

Migrasi dari CLI 2.x

Oktober 2022, dukungan theme masuk ke Shopify CLI 3.0 dengan autentikasi dan pengelolaan toko yang jauh lebih sederhana. Kalau kamu nemu tutorial lama yang pakai CLI 2.x, ini padanannya:

Login: dulu shopify login, sekarang gak perlu, otomatis diminta pas dibutuhin.
shopify whoami: udah gak ada.
Pilih toko: dulu shopify login --store, sekarang flag --store di perintah pertama.
Ganti toko: dulu shopify switch, sekarang --store dengan nilai baru.
Lihat toko aktif: dulu shopify store, sekarang shopify theme info.
Preview: dulu shopify theme serve, sekarang shopify theme dev.
shopify populate buat ngisi data: udah gak ada, diganti data contoh dev store.
Folder: dulu argumen posisi [root], sekarang flag --path.

Cara migrasinya: kalau pakai Homebrew di macOS, cukup brew upgrade shopify-cli. Kalau nggak, uninstall CLI 2.x dulu pakai package manager yang dulu dipakai install (apt, yum, atau gem uninstall shopify-cli), terus install versi baru. Install lewat apt, Yum, dan RubyGems udah gak didukung.

Kalau dua-duanya terpasang, mereka bentrok karena namanya sama (shopify), dan yang jalan itu yang lebih dulu ada di PATH. Detail CLI 2.x-nya ada di 74 Shopify CLI 2.x (deprecated).

Lain-lain

Upgrade: shopify upgrade. Cek versi: shopify version.
Statistik penggunaan anonim dikumpulin secara default. Matiin pakai environment variable SHOPIFY_CLI_NO_ANALYTICS=1.
CLI-nya open source, laporan bug dan permintaan fitur lewat GitHub issues, diskusi di .dev Community.

Ringkasan

Development theme itu theme sementara yang tersembunyi, gak makan jatah theme, dihapus setelah 7 hari gak aktif atau waktu shopify auth logout.
Perintah utamanya: init, dev, pull, push, publish, list, info, check. Plus console buat REPL Liquid dan profile buat ngukur performa.
Tiga cara masuk: akun Shopify (otomatis diminta login), password Theme Access lewat --password, atau token custom app.
--store cuma perlu sekali, diinget seterusnya. Cek pakai shopify theme info.
CLI butuh struktur folder standar. Kalau pakai alat build, jalanin dari folder hasil build.
.shopifyignore buat ngecualiin file, nerima nama file, wildcard, dan regex. Flag --ignore juga bisa dan dua-duanya dihormatin.
Environments di shopify.theme.toml ngumpulin flag jadi satu nama, dipanggil pakai -e nama. Bikin [environments.default] biar gak perlu nyebut terus.
Prioritas nilai: flag perintah > environment variable > file toml.
Jangan naruh flag berbahaya kaya force di environment, nanti delete jalan tanpa konfirmasi.
theme preview --overrides nerapin perubahan virtual lewat source, merge, atau diffs, tanpa nyentuh file di Shopify.
Di CI/CD pakai SHOPIFY_CLI_THEME_TOKEN dan SHOPIFY_FLAG_STORE sebagai secret, plus SHOPIFY_FLAG_FORCE=1 biar gak nunggu prompt.
shopify theme serve di tutorial lama itu shopify theme dev sekarang, dan shopify login udah gak perlu.

Bab selanjutnya kita pindah ke dua alat di dalam Shopify admin: theme editor yang dipakai merchant buat ngatur toko tanpa kode, dan code editor buat edit cepat langsung di browser.

description	Bedah Shopify CLI buat theme, dari development theme, semua perintahnya, environment, sampai CI/CD
tags	shopify, theme, dasar

Sayudha

Penjelajah

05 Shopify CLI

Development Theme

Daftar Perintahnya

Autentikasi dan Akses Toko

2. Password Theme Access

3. Token Custom App

Nyambung ke Toko

Struktur Folder yang Diharapkan

Ngecualiin File

Environments

1. Bikin Environment

2. Pakai Environment

3. Environment Default

4. Urutan Prioritas

5. Banyak Environment Sekaligus

theme preview dan File Overrides

1. source, Ganti Seluruh Isi File

2. merge, Gabungin ke File JSON

3. diffs, Tempel Patch

Shopify CLI di CI/CD

1. Dapetin Password Theme Access

2. Pasang di Pipeline

Liquid Language Server

Migrasi dari CLI 2.x

Lain-lain

Ringkasan

Tampilan Grafik

Daftar Isi

Tautan Balik

Sayudha

Penjelajah

05 Shopify CLI

Development Theme

Daftar Perintahnya

Autentikasi dan Akses Toko

1. Login Pakai Akun Shopify

2. Password Theme Access

3. Token Custom App

Nyambung ke Toko

Struktur Folder yang Diharapkan

Ngecualiin File

Environments

1. Bikin Environment

2. Pakai Environment

3. Environment Default

4. Urutan Prioritas

5. Banyak Environment Sekaligus

theme preview dan File Overrides

1. source, Ganti Seluruh Isi File

2. merge, Gabungin ke File JSON

3. diffs, Tempel Patch

Shopify CLI di CI/CD

1. Dapetin Password Theme Access

2. Pasang di Pipeline

Liquid Language Server

Migrasi dari CLI 2.x

Lain-lain

Ringkasan

Tampilan Grafik

Daftar Isi

Tautan Balik