Terminal guideدليل الطرفية

1. Get started١. البداية

Install with one line. On macOS and Linux:ثبّت البرنامج بسطر واحد. على macOS وLinux:

curl -fsSL https://github.com/Devehab/Locly-DNS/releases/latest/download/install.sh | sh

On Windows (PowerShell):وعلى Windows (عبر PowerShell):

irm https://github.com/Devehab/Locly-DNS/releases/latest/download/install.ps1 | iex

Then see everything LocalDNS can do:ثم اعرض كل ما يستطيع LocalDNS فعله:

localdns info

Administrator rights: adding, changing or removing a name edits your system's hosts file. On macOS and Linux, LocalDNS asks for your password (sudo) for that one command only. On Windows, use a terminal opened with “Run as administrator”. Commands that only read (list, status, doctor, info) never need it.صلاحيات المسؤول: إضافة اسم أو تعديله أو حذفه يعدّل ملف hosts في نظامك. على macOS وLinux يطلب LocalDNS كلمة المرور (sudo) لذلك الأمر وحده. وعلى Windows استخدم طرفية مفتوحة بخيار «تشغيل كمسؤول». أوامر القراءة فقط (list وstatus وdoctor وinfo) لا تحتاجها أبدًا.

2. Add a name٢. إضافة اسم

Give a service a name you choose. The format is always localdns add <name> <ip[:port]>.أعطِ أي خدمة اسمًا تختاره أنت. الصيغة دائمًا localdns add <الاسم> <العنوان[:المنفذ]>.

localdns add app.local 127.0.0.1:3000

You can paste a link as it is, or use localhost: LocalDNS keeps just the address.يمكنك لصق الرابط كما هو، أو استخدام localhost: يأخذ LocalDNS العنوان فقط.

localdns add app.local http://127.0.0.1:3000/

localdns add api.local localhost:3002

A device on your network, with or without a port:جهاز على شبكتك، مع منفذ أو بدونه:

localdns add ha.local 192.168.1.60:8123

localdns add nas.lan 192.168.1.20

Web apps on this computer: use .localhost. Browsers enable some features (many sign-in flows, crypto.subtle, the clipboard, the camera) only on https:// or localhost pages, and they treat any *.localhost name like localhost. So http://app.localhost works exactly like http://localhost:3000 did, while parts of an app may fail at http://app.local. A .localhost name can only point to this computer; for other devices use .local or .lan.تطبيقات الويب على جهازك: استخدم .localhost. المتصفحات لا تفعّل بعض الميزات (مثل كثير من طرق تسجيل الدخول وcrypto.subtle والحافظة والكاميرا) إلا في صفحات https:// أو localhost، وتعامل أي اسم *.localhost مثل localhost. لذلك يعمل http://app.localhost تمامًا كما كان يعمل http://localhost:3000، بينما قد تتعطل أجزاء من التطبيق على http://app.local. واسم .localhost لا يشير إلا إلى هذا الجهاز؛ وللأجهزة الأخرى استخدم .local أو .lan.

localdns add app.localhost 127.0.0.1:3000

Adding the same name with the same address again changes nothing, so scripts can run it safely. To point an existing name somewhere else, use edit.إضافة الاسم نفسه بالعنوان نفسه مرة أخرى لا تغيّر شيئًا، لذلك يمكن للسكربتات تكرارها بأمان. ولتوجيه اسم موجود إلى عنوان آخر استخدم edit.

3. Open it٣. فتح الاسم

With port-free URLs on (the installer turns them on), just open the name:عندما تكون الروابط بدون منفذ مفعّلة (والمثبّت يفعّلها تلقائيًا)، افتح الاسم مباشرة:

http://app.local

The address with the port always works too, router or not:والعنوان مع المنفذ يعمل دائمًا أيضًا، سواء كان الموجّه مفعّلًا أم لا:

http://app.local:3000

Names that point to another device (like ha.local → 192.168.1.60:8123) keep their port: http://ha.local:8123. A page inside your app works as usual: http://app.local/settings.الأسماء التي تشير إلى جهاز آخر (مثل ha.local → 192.168.1.60:8123) تبقى بمنفذها: http://ha.local:8123. وصفحات تطبيقك تعمل كالمعتاد: http://app.local/settings.

4. See your names٤. عرض الأسماء

localdns list

HOSTNAME     ADDRESS           STATUS    OPEN
app.local    127.0.0.1:3000    ✓         http://app.local
ha.local     192.168.1.60      ✓

For details on each name, where files are, and whether LocalDNS can write:لتفاصيل كل اسم، وأماكن الملفات، وهل يستطيع LocalDNS الكتابة:

localdns status

• active: the name works.active (نشط): الاسم يعمل.
• missing: the line was deleted from the hosts file by hand. Restore it with localdns resume <name> or forget it with localdns remove <name>.missing (مفقود): حُذف السطر من ملف hosts يدويًا. أرجِعه بـ localdns resume <الاسم> أو احذفه نهائيًا بـ localdns remove <الاسم>.
• paused: you switched it off (localdns pause). Turn it back on with localdns resume <name>.paused (موقوف مؤقتًا): أوقفته أنت (localdns pause). أعده بـ localdns resume <الاسم>.
• conflict: another line in your hosts file, outside LocalDNS, maps the same name and wins. Remove or rename that line yourself.conflict (تعارض): سطر آخر في ملف hosts، خارج LocalDNS، يعرّف الاسم نفسه ويتقدّم عليه. احذف ذلك السطر أو غيّر اسمه بنفسك.

5. Change or pause a name٥. تعديل اسم أو إيقافه مؤقتًا

Point a name to a new address:وجّه الاسم إلى عنوان جديد:

localdns edit app.local 127.0.0.1:4000

Rename it (the address stays):غيّر الاسم (ويبقى العنوان كما هو):

localdns edit app.local --name web.local

Both at once:أو الاثنين معًا:

localdns edit app.local 127.0.0.1:5173 --name web.local

In the dashboard, use the Edit button next to a name, and click an ending (.localhost, .local…) to swap it. You never need to delete and add again.وفي لوحة التحكم استخدم زر Edit بجانب الاسم، وانقر أي نهاية (.localhost و.local…) لاستبدالها. لن تحتاج أبدًا إلى الحذف ثم الإضافة من جديد.

Pause and resumeالإيقاف المؤقت والإعادة

Switch a name off for a while without losing it: its line leaves the hosts file, so the name stops working, but LocalDNS keeps its address and port.أوقف اسمًا لفترة دون أن تفقده: يخرج سطره من ملف hosts فيتوقف الاسم عن العمل، لكن LocalDNS يحتفظ بعنوانه ومنفذه.

localdns pause app.local

Switch it back on, exactly as it was:وأعده كما كان تمامًا:

localdns resume app.local

In the dashboard, every name has an on/off switch. A paused name shows Paused and keeps its place in the list.وفي لوحة التحكم لكل اسم مفتاح تشغيل وإيقاف. الاسم الموقوف تظهر حالته Paused ويبقى في مكانه في القائمة.

6. Remove a name٦. حذف اسم

localdns remove app.local

It asks first. To skip the question (scripts):يسألك للتأكيد أولًا. ولتخطّي السؤال (في السكربتات):

localdns remove app.local --yes

LocalDNS only removes names it added. Your other hosts entries are never touched.لا يحذف LocalDNS إلا الأسماء التي أضافها هو. مدخلاتك الأخرى في ملف hosts لا تُمس أبدًا.

7. The dashboard٧. لوحة التحكم

localdns ui

It opens in your browser at a name, so there is no IP to remember:تُفتح في متصفحك باسم، فلا تحتاج إلى حفظ أي عنوان IP:

http://localdns.local

It is always reachable at its direct address too, even when port-free URLs are off:ويمكن الوصول إليها دائمًا عبر عنوانها المباشر أيضًا، حتى عندما تكون الروابط بدون منفذ معطّلة:

http://127.0.0.1:7357

The dashboard runs while that terminal is open; press Ctrl+C to stop it. On macOS and Linux it asks for your password so it can add, edit and delete names. Options:تعمل لوحة التحكم ما دامت تلك الطرفية مفتوحة، واضغط Ctrl+C لإيقافها. على macOS وLinux تطلب كلمة المرور لتتمكن من الإضافة والتعديل والحذف. الخيارات:

8. Port-free URLs٨. روابط بدون منفذ

The hosts file can store a name and an address, but never a port. The LocalDNS router fills that gap: it listens on 127.0.0.1:80 (this computer only) and forwards each of your names to its port. It never runs as root and starts on its own.ملف hosts يحفظ الاسم والعنوان فقط، ولا يحفظ المنفذ أبدًا. موجّه LocalDNS يسدّ هذه الفجوة: يستمع على 127.0.0.1:80 (هذا الجهاز فقط) ويحوّل كل اسم من أسمائك إلى منفذه. لا يعمل أبدًا بصلاحيات root، ويبدأ تلقائيًا.

Turning it off? While it is off, the dashboard only opens at http://127.0.0.1:7357 (run localdns ui first), not at http://localdns.local. Keep that address: it is where you switch port-free URLs back on, or run localdns router enable.ستوقفه؟ ما دام متوقفًا، تُفتح لوحة التحكم فقط على http://127.0.0.1:7357 (بعد تشغيل localdns ui)، وليس على http://localdns.local. احتفظ بهذا العنوان: منه تعيد تفعيل الروابط بدون منفذ، أو شغّل localdns router enable.

9. Fix problems٩. حل المشكلات

Start here: it checks everything and prints a fix for each problem.ابدأ من هنا: يفحص كل شيء ويطبع طريقة إصلاح كل مشكلة.

localdns doctor

The app opens, but some features don't work (sign-in, uploads…)التطبيق يُفتح، لكن بعض الميزات لا تعمل (تسجيل الدخول، رفع الملفات…)

A browser console error like Cannot read properties of undefined (reading 'digest') means the page isn't treated as secure: browsers enable those features only on https:// or localhost pages. Rename the entry to .localhost, which browsers treat like localhost:خطأ في لوحة المتصفح مثل Cannot read properties of undefined (reading 'digest') يعني أن الصفحة لا تُعتبر آمنة: المتصفحات تفعّل هذه الميزات فقط في صفحات https:// أو localhost. غيّر الاسم إلى نهاية .localhost، التي تعاملها المتصفحات مثل localhost:

localdns edit app.local --name app.localhost

If sign-in still fails, add the new address (http://app.localhost) to the app's allowed sign-in or callback URLs.وإذا بقي تسجيل الدخول لا يعمل، فأضف العنوان الجديد (http://app.localhost) إلى روابط تسجيل الدخول أو الرجوع المسموحة في إعدادات التطبيق.

The name doesn't open at allالاسم لا يفتح إطلاقًا

Your system or browser may remember the old answer. Open a new tab, or clear the cache. macOS:قد يتذكّر النظام أو المتصفح النتيجة القديمة. افتح تبويبًا جديدًا، أو امسح الذاكرة المؤقتة. على macOS:

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

Windows:وعلى Windows:

ipconfig /flushdns

It works with the port but not without itيعمل مع المنفذ ولا يعمل بدونه

Check the router with localdns router. If it is off, run localdns router enable. If another program (Apache, nginx…) uses port 80, stop it. The name must point to 127.0.0.1 and have a port.افحص الموجّه بـ localdns router. إن كان متوقفًا فشغّل localdns router enable. وإن كان برنامج آخر (Apache أو nginx…) يستخدم المنفذ 80 فأوقفه. ويجب أن يشير الاسم إلى 127.0.0.1 مع منفذ.

“Nothing is running on 127.0.0.1:3000”«Nothing is running on 127.0.0.1:3000»

The name works, but your app isn't running on that port. Start your app, or fix the port with localdns edit.الاسم يعمل، لكن تطبيقك لا يعمل على ذلك المنفذ. شغّل تطبيقك، أو صحّح المنفذ بـ localdns edit.

“needs administrator rights”«needs administrator rights»

Run the command with sudo (macOS/Linux) or from an administrator terminal (Windows).شغّل الأمر مع sudo (على macOS وLinux) أو من طرفية بصلاحيات المسؤول (على Windows).

.local names are slow on my Macأسماء .local بطيئة على جهاز Mac

macOS also uses .local for Bonjour. If you notice delays, use .test names instead.يستخدم macOS اللاحقة .local أيضًا لخدمة Bonjour. إذا لاحظت تأخيرًا فاستخدم أسماء تنتهي بـ .test.

10. Scripts and AI agents١٠. السكربتات ووكلاء الذكاء الاصطناعي

Every command accepts --json (errors too), and never waits for input when there is no terminal. Use --yes to confirm removals.كل أمر يقبل --json (والأخطاء أيضًا)، ولا ينتظر أي إدخال عندما لا توجد طرفية. استخدم --yes لتأكيد الحذف.

localdns add app.local 127.0.0.1:3000 --json

localdns list --json

localdns remove app.local --yes --json

Exit codesرموز الخروج

11. Uninstall١١. إزالة البرنامج

localdns uninstall

Removes LocalDNS's names, its settings, the router and the program. Your other hosts entries are not touched. In scripts: localdns uninstall --yes.يحذف أسماء LocalDNS وإعداداته والموجّه والبرنامج نفسه. مدخلاتك الأخرى في ملف hosts لا تُمس. وفي السكربتات: localdns uninstall --yes.

12. All commands١٢. كل الأوامر