Hulak

رسائلك في الطرفية.

البدء السريع • مستكشف GraphQL • تخطيط المشروع • التوثيق

---

شغّل طلبًا واحدًا، أو مجلدًا كاملًا، أو ابقَ تفاعليًا

hulak run ./requests/

يشغّل Hulak ملفات الطلبات مباشرة من مشروعك. يدعم التنفيذ المتزامن للمجلدات. ويعود إلى منتقي تفاعلي عند تشغيل hulak فقط.

مستكشف GraphQL المخصص

تصفّح المخططات من نقاط نهاية متعددة. ابحث في العمليات. ابنِ الاستعلامات تفاعليًا. نفّذها مباشرة. احفظ الملفات المُنشأة من الطرفية.

البدء السريع

التثبيت

يُوزَّع Hulak عبر xaaha/tap. يتطلب Homebrew 6.0+ ثقة صريحة للمستودعات الخارجية؛ بدونها يتخطى brew upgrade أداة hulak بصمت. خطوة لمرة واحدة لكل جهاز:

brew trust xaaha/tap
brew install --cask xaaha/tap/hulak

خيارات تثبيت أخرى:

• go install github.com/xaaha/hulak@latest
• البناء من المصدر باستخدام go build -o hulak

إكمال الصدفة (go install / البناء من المصدر)

يثبّت Homebrew الإكمال تلقائيًا. إذا ثبّت عبر go install أو بنيت من المصدر، ففعّله مرة واحدة:

# zsh
hulak completion zsh > "${fpath[1]}/_hulak"        # then restart your shell

# bash (macOS, Homebrew bash-completion)
hulak completion bash > $(brew --prefix)/etc/bash_completion.d/hulak

# bash (Linux)
hulak completion bash | sudo tee /etc/bash_completion.d/hulak >/dev/null

يتطلب Zsh وجود autoload -Uz compinit && compinit في ملف .zshrc الخاص بك.

المسار أ. عميل API مع أسرار مشفّرة (الافتراضي)

mkdir my-apis && cd my-apis
hulak init # creates .hulak/store.age + identity

أنشئ طلبًا مبدئيًا؛ للتحقق سريعًا من شكل ملف الطلب شغّل:

hulak example api  # writes example-api.hk.yaml you can run

[!Note] للأنواع الأخرى شغّل: hulak example. يمنحك الأمر الفرعي example طريقة سريعة لكتابة ملف طلب يمكنك تعديله. لمزيد من المعلومات شغّل hulak example -h

لإعداد سر يمكنك تشغيل:

hulak secrets keys set placeholder  https://jsonplaceholder.typicode.com/posts -env prod

الآن، في ملف example-api.hk.yaml الخاص بك، يمكنك الإشارة إلى هذا السر:

method: POST
url: "{{.placeholder}}"
# rest of the body of the file remains same

شغّل الطلب:

hulak run example-api.hk.yaml --env prod

تفضّل ملفات env/*.env النصية بدلًا من الأسرار المشفّرة؟

hulak init classic

الوضع النصي مدعوم بالكامل. راجع docs/environment.md لمزيد من المعلومات

خزنة الأسرار المشفّرة أو ملفات .env النصية

يعمل Hulak في وضعين. اختر مرة واحدة أثناء hulak init. يمكنك الترحيل لاحقًا.

• الخزنة (الافتراضي): تعيش الأسرار في .hulak/store.age، مشفّرة بمفتاح age أو زوج مفاتيح SSH. آمنة للإيداع. تشاركها الفرق عبر ملف المستلمين. راجع docs/store.md.
• النصي: تعيش الأسرار في ملفات env/*.env النصية. أبسط، بلا تشفير. أضف env/ إلى .gitignore. راجع docs/environment.md.

تشغّل الوضع الكلاسيكي وتريد التبديل؟ راجع docs/migrating-to-vault.md.

استخدمه من وكيل ذكاء اصطناعي (MCP)

يوفّر Hulak خادم MCP مدمجًا، حتى يتمكن وكلاء مثل Claude Code وCursor وZed من تشغيل مجموعة API الخاصة بك بلغة طبيعية — "اعرض الطلبات"، "نفّذ login تجريبيًا على staging"، "استدعِ getUser واعرض الاستجابة".

لـ Claude Code، أضفه بأمر واحد:

claude mcp add hulak -s user -- hulak mcp --project api=~/work/api-tests

يستخدم Cursor وZed وCodex وopencode وPi ملف إعداد صغير بدلًا من ذلك. راجع docs/mcp.md لكل منها.

لا تغادر الأسرار جهازك أبدًا: يعمل الوكيل مع أسماء الطلبات والبيئات، وليس القيم المفكوكة. القراءات والتنفيذات التجريبية للقراءة فقط؛ والكتابات مُتحقَّق منها بالمخطط؛ ولا تُحفظ ملفات الاستجابة إلا عند الطلب.

الإعداد الكامل، ومرجع الأدوات، ونموذج الأمان: docs/mcp.md.

الأوامر

الأمر	الغرض	اقرأ المزيد
run	تنفيذ ملف/ملفات طلب أو مجلد	body.md, actions.md
gql	واجهة مستكشف GraphQL النصية	graphql-explorer.md
secrets	إدارة الخزنة المشفّرة	store.md
init	تهيئة مشروع hulak	store.md
migrate	تحويل Postman إلى hulak	migrating-to-vault.md
example	إنشاء ملفات طلبات نموذجية	—
doctor	فحص صحة المشروع	—
mcp	تقديم الطلبات لوكلاء الذكاء الاصطناعي عبر MCP	mcp.md
version	طباعة الإصدار	—

شغّل hulak <command> --help للأعلام وأمثلة كل أمر.

سلوك المنتقي

حذف --env يفتح منتقيًا تفاعليًا.

• hulak run وhulak gql يطلبان فقط عندما تشير الملفات إلى {{.key}}.
• الأوامر الفرعية لـ hulak secrets تطلب في كل مرة (باستثناء secrets list).
• تتطلب الصدفات غير التفاعلية --env <name>.

المزالق الشائعة

• لا تُودع ~/.config/hulak/identity.txt أبدًا. هذا مفتاحك الخاص. الوضع 0600. انسخه احتياطيًا أولًا. راجع docs/store.md#identity-backup.
• عند hulak init، ينشئ -env ملفات البيئة. إنه علم إعداد، وليس محددًا وقت التشغيل. hulak init -env staging prod ينشئ بيئتين.
• env اسم مستعار لـ secrets. hulak env list يعمل بنفس طريقة hulak secrets list.
• تحتاج محررات الواجهة الرسومية إلى علم انتظار لـ secrets edit. استخدم EDITOR="code -w" أو EDITOR="zed --wait". بدونه يعود المحرر فورًا وتُفقد التغييرات.
• تعارضات الدمج على store.age تحتاج إلى وصفة. راجع docs/versioning.md#merge-conflicts.

تخطيط المشروع

my-project/
├── .hulak/
│   ├── store.age          # encrypted secrets (safe to commit)
│   └── recipients.txt     # public keys of recipients (safe to commit)
├── requests/
│   ├── create-user.hk.yaml
│   └── get-user.hk.yaml
└── (your project files)

~/.config/hulak/
└── identity.txt           # YOUR private key. NEVER commit. Mode 0600.

مستكشف GraphQL

ابدأ المستكشف بملف أو مجلد:

hulak gql e2etests/gql_schemas/countries.yml
hulak gql .
hulak gql -env staging ./collections/graphql