مرجع الأداة

الحزمة @dukkan.one/cli هي سطر أوامر مطوّري دكان للثيمات والتطبيقات؛ الأمر الثنائي dukkan. تتطلب Node.js 18.17 أو أحدث، وتعمل على متجر تجريبي واحد فقط ولا تلمس أي متجر حقيقي. ما زالت @dukkan.one/theme-cli تُثبَّت وتحوّل إليها مع تنبيه إهمال؛ انقل سكربتاتك إلى الاسم الجديد.

npx @dukkan.one/cli COMMAND
# or, after a global install: dukkan COMMAND

رموز الخروج#

كل رسالة فشل تبدأ بـ ✗، والنجاح بـ ✓، والتحذير بـ !.

login#

npx @dukkan.one/cli login

تسجيل دخول بتدفق رمز الجهاز (RFC 8628):

  Open:  https://developer.dukkan.one/cli/authorize?code=DKN-7RX2MK
  Code:  DKN-7RX2MK

  Waiting for approval in the portal…
✓ Signed in. The CLI can now push themes to your sandbox store.

• الرمز بصيغة DKN-XXXXXX من الحروف والأرقام غير الملتبسة (BCDFGHJKMNPQRSTVWXYZ23456789)، وصالح 10 دقائق.
• تفتح الرابط، تؤكّد الرمز، وتختار المتجر التجريبي. تستطلع الأداة البوابة كل 5 ثوانٍ (وتزيد ثانيتين عند slow_down).
• ينتج زوج رموز dk_cli_at_ (ساعة) وdk_cli_rt_ (30 يوماً) مربوط بذلك المتجر التجريبي، ويُجدَّد تلقائياً عند 401؛ إعادة استخدام رمز تحديث قديم تلغي السلسلة.

أخطاء الخادم 5xx أثناء الاستطلاع لا تُنهي التسجيل؛ تتراجع الأداة حتى 15 ثانية وتواصل حتى انتهاء الرمز.

أوامر الثيمات#

لم تتغيّر عن @dukkan.one/theme-cli؛ الدليل الكامل في ابنِ ثيماً.

theme init [dir]#

npx @dukkan.one/cli theme init my-theme

ينشئ 4 ملفات: layout/theme.liquid وtemplates/home.liquid وconfig/settings_schema.json وlocales/ar.json. يطبع ✓ Starter theme created (4 files).

theme check [dir] [--remote]#

npx @dukkan.one/cli theme check
npx @dukkan.one/cli theme check --remote

يتحقّق من المجلد محلياً بالشيفرة نفسها التي يطبّقها الخادم عند الدفع، ويطبع ✓ Bundle valid — N files, hash … أو قائمة ✗. مع --remote يرسل الحزمة إلى POST /theme-api/v1/theme/check لتصيير تجريبي (يتطلب تسجيل دخول) ويطبع ✓ Server sandbox render passed.. القواعد ونصوص الأخطاء في فحص الثيم. لا يحتاج الفحص المحلي إلى تسجيل دخول.

theme push [dir] [--name <name>]#

npx @dukkan.one/cli theme push --name "Damascus Gold"

يتحقّق محلياً ثم يرسل الحزمة إلى PUT /theme-api/v1/theme/draft. كل محتوى جديد يصبح إصداراً ثابتاً ببصمة تجزئة ويُثبَّت مسودةً للمتجر التجريبي؛ الحزمة المطابقة لا تنشئ شيئاً.

✓ Pushed version 7 (3f9a1c2b7d4e…)
✓ No changes — version 7 already on the server.

• --name اسم العرض (حتى 80 حرفاً)؛ الافتراضي External theme. الاسم في الإدراج المراجَع هو ما يراه التاجر.
• هوية الثيم تُشتق على الخادم من المتجر التجريبي (sandbox-<id>)؛ متجر تجريبي واحد لكل ثيم.
• رفض الخادم يظهر كـ ✗ Theme bundle rejected — {"errors":[…]}.

theme pull [dir]#

npx @dukkan.one/cli theme pull ./restored

ينزّل مسودة المتجر التجريبي الحالية ويطبع ✓ Pulled N files (version …). ترفض الأداة أي مسار يخرج عن المجلد الهدف.

theme dev [dir]#

npx @dukkan.one/cli theme dev

يدفع مرة، يطلب رابط معاينة من POST /theme-api/v1/theme/preview، ثم يراقب المجلد ويدفع عند كل تغيير:

✓ Version 7 live in preview:

  https://dukkan.one/stores/YOUR_SANDBOX_SLUG?__preview=TOKEN

  Watching for changes — Ctrl+C to stop.
✓ 14:05:12 version 8 — https://dukkan.one/stores/YOUR_SANDBOX_SLUG?__preview=NEW_TOKEN

يصلح رابط المعاينة 24 ساعة ويُبطَل تلقائياً عندما تتغيّر المسودة (draft_rev)، فتطبع الأداة رابطاً جديداً بعد كل دفعة مغيّرة فقط. التغييرات المتلاحقة تُدمج؛ الدفعة الفاشلة تطبع ✗ وتستمر المراقبة.

أوامر التطبيقات#

تبني أوامر app تطبيق دكان على @dukkan.one/app-sdk وتشغّله وتضبطه على متجرك التجريبي. تعدّل مسودات الإصدارات فقط، ولا تفعّل إصداراً أبداً، ولا تتعامل مع أسرار توقيع Webhooks أبداً. يقبل كل أمر --json لكائن JSON واحد في كل سطر بلا رموز.

app init [dir]#

npx @dukkan.one/cli app init my-app

ينشئ هيكل تطبيق Nuxt 4 على @dukkan.one/nuxt: ملف dukkan.app.toml و.env.example وserver/dukkan.ts وصفحة هبوط بحالات التاجر (متصل، إعادة الاتصال، مُزال، غير مثبّت) وقائمة إعداد للمطوّر. يسأل عن الاسم والقالب والنطاقات؛ ولكل سؤال راية للسكربتات.

✓ Created my-app in /home/dev/my-app (14 files, template nuxt-minimal).
Next:
  cd my-app && npm install
  cp .env.example .env   # then fill in the client secret from the portal
  dukkan login            # once, binds the CLI to your sandbox store
  dukkan app dev          # tunnel, install link, live events

طلب clients:read يطبع تحذيراً: تتطلب البوابة قبول اتفاقية معالجة البيانات قبل أن تحمله مسودة (النطاقات).

app list#

npx @dukkan.one/cli app list

تطبيقات فريقك مع أرقام إصدارات المسودة والنشط ومعرّفاتها. المعرّف هو ما يأخذه --app؛ وتتذكره الأوامر في .dukkan/state.json بعد أول استخدام.

app config pull وapp config push#

npx @dukkan.one/cli app config pull
npx @dukkan.one/cli app config push

يكتب pull مسودة إصدار البوابة (أو الإصدار النشط عندما لا توجد مسودة) في dukkan.app.toml، بما فيها app.client_id. ويرسل push الملف إلى المسودة: ينشئها عندما لا توجد، ويطبع الفرق، ويسأل قبل إزالة نطاق، ولا يفعّل أبداً. تعرض البوابة الإصدار بعدها على أنه يُدار من الملف. القواعد وتنبيه الاختلاف و--force في ملف dukkan.app.toml.

Updating draft version 4 of Order notifier:
  + scope: orders:write
  - topic: product.updated
✓ Updated draft version 4; the portal now shows it as managed by dukkan.app.toml.
Make it active in the portal when ready: https://developer.dukkan.one/dashboard/apps/APP_ID

app dev [dir]#

npx @dukkan.one/cli app dev

يشغّل التطبيق، ويفتح نفق cloudflared سريعاً، ويسجّل جلسة تطوير في البوابة (رابط إعادة التوجيه ونقطة نهاية النفق، صالحة 8 ساعات على الأكثر، للمتجر التجريبي فقط)، ويخبر التطبيق العامل برابطه العام، ويطبع رابط تثبيت لمتجرك التجريبي، ثم يبثّ كل تسليم للمتجر التجريبي حتى Ctrl+C. تُحذف الجلسة عند الخروج. الشرح الكامل في البداية السريعة.

✓ 14:05:12 order.created                9f3a1c2b  200 test
✗ 14:06:40 order.paid                   0b7e55d1  500

كل سطر تسليم: رمز الحالة، والوقت، والموضوع، وأول 8 أحرف من معرّف الحدث، وحالة الاستجابة التي أجاب بها تطبيقك (أو رمز خطأ المنصّة)، وtest للتجارب. تعني 500 أن معالجك أطلق خطأ؛ تعيد المنصّة المحاولة وفق جدولها.

app webhook trigger <topic>#

npx @dukkan.one/cli app webhook trigger order.created

يطلب من المنصّة إطلاق تجربة موقّعة واحدة للموضوع إلى التطبيق العامل، عبر صندوق الصادر وعامل التسليم الحقيقيين، بعيّنة مبنية من بيانات متجرك التجريبي المزروعة. المتاجر التجريبية فقط؛ ويجب أن يتضمن الاشتراك الموضوع. لا ترى الأداة سر التوقيع أبداً.

✓ order.created queued as event 9f3a1c2b… (1 delivery). Watch it arrive in `dukkan app dev`.
  → https://lively-otter-1234.trycloudflare.com/dukkan/webhooks (delivery 4c1d9e0a…)

--local موجود لاختبارات الوحدة غير المتصلة لمعالجك: تمرّر السر الذي خزّنه تطبيقك فيتحقق التسليم، لكن لا شيء يمرّ عبر المنصّة.

app logs#

npx @dukkan.one/cli app logs --follow

تاريخ تسليمات تطبيقك على متجرك التجريبي، الأحدث أولاً، بصيغة الأسطر نفسها في app dev. يواصل --follow المتابعة، ويحدد -n, --limit <n> عدد الأسطر (الافتراضي 30)، ويبدأ --since <iso> بعد لحظة معيّنة.

الملفات#

{
  "portal_url": "https://developer.dukkan.one",
  "api_url": "https://dukkan.one",
  "access_token": "dk_cli_at_REDACTED",
  "refresh_token": "dk_cli_rt_REDACTED",
  "development_store_id": "5d2f8c1e-9a44-4e8b-b7a9-3065a1f20c4d"
}

تسريب الملف يعرّض مسودات ثيم متجر تجريبي واحد فقط، وتلغي سلسلة التحديث نفسها عند إعادة الاستخدام. لا تطبع الأداة قيم الرموز أبداً.

متغيرات البيئة#

DUKKAN_CLI ليس متغيراً للأداة نفسها بل لأدوات مستودع dukkan-themes: يوجّهها إلى نسخة غير منشورة (DUKKAN_CLI=/path/to/app/cli/dist/index.js)؛ راجع تأخّر المدقّق.

حلّ المشكلات#