البدء

تسحب أداة OneGuard في سطر الأوامر متغيرات البيئة المشفّرة إلى ملف .env محلي، وتدفع التغييرات مرة أخرى، وتدير الخزنات والأسرار وأعضاء الفريق — دون مغادرة الطرفية.

التثبيت

macOS و Linux

تنشر OneGuard من مستودع Homebrew خاص بها ("tap")، فتوجّه Homebrew إليه مرة واحدة:

brew tap oneguard-sa/oneguard
brew install oneguard

أو بأمر واحد يجمع بين الإضافة والتثبيت:

brew install oneguard-sa/oneguard/oneguard

تحقّق من نجاح التثبيت:

oneguard --version
oneguard --help
which oneguard

Windows

دعم Chocolatey قيد الإنجاز:

choco install oneguard

وحيث لا يوجد مخزن كهذا — داخل حاوية أو على خادم مجرّد — تتراجع الأداة إلى ~/.oneguard/credentials.json بصلاحية 600 وتنبّهك إلى ذلك. على تلك الأجهزة فضّل متغيّر البيئة أدناه، فهو لا يخزّن شيئًا إطلاقًا.

لتسجيل الخروج:

oneguard auth logout

في CI والحاويات والسكربتات

اضبط ONEGUARD_API_KEY واستغنِ عن auth login كليًا. لا يُكتب شيء على القرص ولا يُقرأ منه شيء:

ONEGUARD_API_KEY=og_your_key oneguard env pull --id 84e1d2b3

وبهذه الطريقة نفسها يوثّق خادم MCP الأداةَ، ولهذا لا تترك جلسة الوكيل أي بيانات اعتماد خلفها.

صلاحيات المفتاح

يُنشأ المفتاح إما للقراءة read أو للكتابة write، ويفرض الخادم هذا الفرق:

| الصلاحية | ما يمكن فعله | | --- | --- | | read | status، vault list، secrets list، env pull، env sync، teams list، logs list، وgenerate (التي لا تغادر جهازك أبدًا) | | write | كل ما سبق، بالإضافة إلى إنشاء الأسرار والخزنات وتعديلها وأرشفتها وحذفها، وenv sync --push، وsecrets generate، ودعوة الأعضاء أو إزالتهم |

مفتاح للقراءة فقط يُستخدم في عملية كتابة يُرفض برسالة واضحة، وهذا لا يسجّل خروجك — تبقى جلستك صالحة، وكل ما تحتاجه مفتاح بصلاحية الكتابة لتلك العملية.

لمعرفة ما يستطيع المفتاح الذي تستخدمه حاليًا فعله:

oneguard status

مخرجات قابلة للقراءة آليًا

يقبل أي أمر خيار --json العام، فيستبدل النص الموجّه للبشر بكائن JSON واحد. ويأتي الخيار قبل الأمر:

oneguard --json vault list
oneguard --json status

{"ok":true,"vaults":[{"id":"0d8ac74c-…-…","id_prefix":"0d8ac74c","name":"oneguard-api"}],"count":1}

ثلاثة أمور تستحق الانتباه:

الأخطاء أيضًا JSON، على stdout، مع رمز خروج غير صفري: {"ok":false,"error":{"code":"forbidden","message":"…"}}. والحقل code ثابت — لا يتغيّر عند إعادة صياغة الرسالة — فالتفريع عليه آمن.
المعرّفات تعود كاملة. المخرجات البشرية تقتصّها إلى ثمانية أحرف لتبقى مقروءة، أما JSON فلا.
القيم لا تظهر أبدًا. الأوامر التي تنقل .env تُبلّغ عن أسماء المتغيّرات وعددها. أما القيم فتذهب إلى الملف ولا شيء غيره.

ويرفض oneguard env sync تشغيل قائمة اختيار الخزنة التفاعلية مع --json، إذ لا يستطيع سكربت الإجابة على سؤال — اربط المجلد مرة واحدة دون الخيار، ثم يعمل كل تشغيل بعدها معه.

الترقية

brew update
brew upgrade oneguard

لمعرفة ما تستخدمه مقابل المتاح:

oneguard --help
brew info oneguard

إذا أفاد brew upgrade بعدم وجود جديد رغم توقّعك إصدارًا أحدث، فربما تكون نسخة Homebrew من الـ tap قديمة — ينعشها brew update. لإعادة تثبيت كاملة:

brew uninstall oneguard && brew install oneguard-sa/oneguard/oneguard

تشغيل نسخة محلية

عند العمل على الأداة نفسها، شغّل نسختك المبنية محليًا دون التأثير على النسخة المثبَّتة. لا تضعها على PATH:

cd oneguard_cli
dart compile exe bin/oneguard.dart -o build/oneguard
./build/oneguard vault list

تشترك كل نسخة من الأداة على الجهاز في بيانات اعتماد واحدة. لإبقاء تسجيل دخول تجريبي منفصلًا، امنح نسختك مجلد home مختلفًا — فاسم المدخل في مخزن بيانات الاعتماد مشتقّ من مجلد الإعدادات، وبالتالي home مختلف يعني مدخلًا مختلفًا:

HOME=/tmp/oneguard-dev ./build/oneguard auth login og_test_key
HOME=/tmp/oneguard-dev ./build/oneguard status

أو، أبسط من ذلك، مرّر المفتاح في البيئة ولا تخزّن شيئًا:

ONEGUARD_API_KEY=og_test_key ./build/oneguard status

في الحالتين تبقى جلستك الحقيقية دون تأثير. (والأولى هي تحديدًا كيف يعزل خادم MCP نفسه.)