'\" t
.\"     Title: rad
.\"    Author: The Radicle Team
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-08-28
.\"    Manual: Radicle CLI Manual
.\"    Source: rad 1.0.0
.\"  Language: English
.\"
.TH "RAD" "1" "2026-08-28" "rad 1.0.0" "Radicle CLI Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "نام (NAME)"
rad \- ابزارهای خط فرمان Radicle
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBrad\fP *
.SH "توضیحات (DESCRIPTION)"
.sp
رابط خط فرمان (CLI) Radicle مجموعه‌ای از ابزارهاست که برای کاربران پشتهٔ
همکاری کد همتا‌به‌همتای (peer\-to\-peer) Radicle طراحی شده است. این ابزار خط فرمان
قابلیت مدیریت پروفایل‌های Radicle و انتشار مخازن در شبکهٔ Radicle را فراهم می‌کند.
.SH "نیازمندی‌ها (REQUIREMENTS)"
.sp
چند نیازمندی مهم برای اجرای CLI رادیکال وجود دارد: نخست، باید نسخهٔ جدیدی
از \fBgit\fP (نسخهٔ \fB2.34.0\fP یا جدیدتر) نصب شده باشد. می‌توانید وضعیت نصب را
با اجرای \fBgit \-\-version\fP بررسی کنید. دوم، \fBssh\-agent\fP باید نصب و در حال
اجرا باشد. برای دور زدن ssh\-agent، می‌توان متغیر محیطی \fBRAD_PASSPHRASE\fP را
تنظیم کرد. به بخش \fIمحیط (ENVIRONMENT)\fP مراجعه کنید.
.SH "شروع به کار (GETTING STARTED)"
.sp
بیایید ببینیم چگونه می‌توان Radicle را راه‌اندازی و یک مخزن را از شبکه کلون کرد.
.sp
پیش از شروع، با اجرای دستور زیر مطمئن شوید که باینری \fBrad\fP در سیستم شما
در دسترس است:
.sp
.if n .RS 4
.nf
.fam C
$ rad
.fam
.fi
.if n .RE
.sp
این دستور پایه است و خروجی آن تمامی زیردستورهای (sub\-commands) موجود را نمایش
خواهد داد.
.SS "ایجاد یک پروفایل (Creating a profile)"
.sp
هنگام استفاده از Radicle برای نخستین بار، باید یک \fIپروفایل\fP جدید Radicle ایجاد
کنید. یک پروفایل صرفاً یک جفت‌کلید رمزنگاری است که با مقداری فضای ذخیره‌سازی در
دستگاه محلی شما پیوند دارد. Radicle همه‌چیز را در دایرکتوری \fIخانه\fP (home) رادیکال
ذخیره می‌کند که در بیشتر سیستم‌ها به‌طور پیش‌فرض \fB~/.radicle\fP است.
برای ایجاد پروفایل خود، دستور زیر را اجرا کنید:
.sp
.if n .RS 4
.nf
.fam C
$ rad auth
.fam
.fi
.if n .RE
.sp
با وارد کردن یک نام مستعار (alias) و یک عبارت عبور (passphrase) برای محافظت از
جفت‌کلید خود، مراحل را دنبال کنید. پس از پایان مراحل، \fIDID\fP (شناسه نامتمرکز یا
Decentralized Identifier) جدید Radicle شما نمایش داده خواهد شد. این شناسه، دستگاه
شما و همچنین تمام کدهایی را که منتشر می‌کنید مشخص می‌سازد. آن را آزادانه با همکاران
به اشتراک بگذارید. نام مستعار شما یک نام غیریکتا است که در سراسر شبکه برای شناسایی
گره (node) شما به اشتراک گذاشته می‌شود و همیشه می‌توانید بعداً آن را تغییر دهید.
.sp
پس از اجرای \fBrad auth\fP، باید یک پروفایل و جفت‌کلید جدید در دایرکتوری خانهٔ
Radicle خود داشته باشید. این جفت‌کلید برای شناسایی همتاها در سراسر شبکه و همچنین
امضای کدها و سایر مصنوعات (artifacts) منتشرشده در شبکه استفاده می‌شود.
.sp
برای جلوگیری از نیاز به وارد کردن مجدد عبارت عبور در هر بار نیاز به امضا،
\fBrad auth\fP کلید خصوصی شما را به \fBssh\-agent\fP اضافه می‌کند.
.sp
همیشه می‌توانید مسیر کامل دایرکتوری خانهٔ Radicle خود را با دستور زیر نمایش دهید:
.sp
.if n .RS 4
.nf
.fam C
$ rad self \-\-home
.fam
.fi
.if n .RE
.sp
زیردستور \fBself\fP برای استعلام اطلاعات پروفایل مفید است. می‌توانید آن را بدون هیچ
آرگومانی اجرا کنید تا تمام اطلاعات پروفایل شما، از جمله DID نمایش داده شود:
.sp
.if n .RS 4
.nf
.fam C
$ rad self
.fam
.fi
.if n .RE.SS "اتصال به شبکه (Connecting to the network)"
.sp
سامانه Radicle یک سیستم peer\-to\-peer است. بدین معنا که هیچ کلاینت یا
سروری وجود ندارد؛ فقط \fIگره‌ها\fP هستند و هر کاربر باید گره متعلق به خود را
اجرا کند. این امر تضمین می‌کند که هیچ نقطه شکست واحدی وجود نداشته باشد و
شبکه Radicle بتواند تا زمانی که کاربرانی برای اجرای گره‌ها وجود دارند، به
حیات خود ادامه دهد.
.sp
گره Radicle یک فرایند سبک‌وزن است که در پس‌زمینه اجرا می‌شود و اتصالات با
گره‌های دیگر و همچنین تکثیر داده‌ها (data replication) را مدیریت می‌کند. برای
بررسی وضعیت گره خود، این دستور را اجرا کنید:
.sp
.if n .RS 4
.nf
.fam C
$ rad node status
.fam
.fi
.if n .RE
.sp
اگر گره در حال اجرا نیست، می‌توانید آن را با دستور زیر راه‌اندازی کنید:
.sp
.if n .RS 4
.nf
.fam C
$ rad node start
.fam
.fi
.if n .RE
.sp
این کار گره را در پیش‌زمینه (foreground) راه‌اندازی می‌کند. کافی است
\fB\-\-daemon\fP را اضافه کنید تا گره در پس‌زمینه اجرا شود.
.sp
در صورت تبدیل شدن به دیمن، گره تمام خروجی‌ها را در فایلی در دایرکتوری خانگی
Radicle شما ثبت می‌کند. در بیشتر سیستم‌ها، این مسیر
\fB~/.radicle/node/node.log\fP خواهد بود.
.sp
همچنین می‌توانید در هر زمان با استفاده از دستور زیر آخرین گزارش‌ها را مشاهده کنید:
.sp
.if n .RS 4
.nf
.fam C
$ rad node logs
.fam
.fi
.if n .RE
.sp
پس از راه‌اندازی گره شما، تلاش خواهد کرد به همتاها (peers) در شبکه متصل شود.
.sp
توجه داشته باشید که اگر گره خود را طوری تنظیم کنید که با استفاده از \fBsystemd\fP(1)
راه‌اندازی شود، گزارش‌ها به ژورنال سیستم ارسال خواهند شد. این گزارش‌ها را می‌توان با
\fBjournalctl\fP(1) مشاهده کرد:
.sp
.if n .RS 4
.nf
.fam C
$ journalctl \-u radicle\-node \-S today
.fam
.fi
.if n .RE
.sp
برای اتصال به یک همتای مشخص، می‌توان از زیردستور \fBconnect\fP استفاده کرد:
برای مثال، جهت اتصال به یک گره عمومی (community node)، می‌توانید دستور زیر را اجرا کنید:
.sp
.if n .RS 4
.nf
.fam C
$ rad node connect z6MkrLMMsiPWUcNPHcRajuMi9mDfYckSoJyPwwnknocNYPm7@iris.radicle.network:8776
.fam
.fi
.if n .RE
.sp
آرگومان ارائه‌شده به \fBconnect\fP، \fIنشانی\fP (address) گره نامیده می‌شود. این نشانی
از یک شناسه گره (NID)، به دنبال آن نماد \fB@\fP، و نام \fIhost\fP و \fIport\fP
تشکیل شده است. می‌توانید NID خود را با \fBrad node status\fP مشاهده کنید.
.sp
برای دائمی کردن این اتصالات، به گونه‌ای که همیشه در هنگام راه‌اندازی آزموده شوند،
نشانی‌ها را به فایل پیکربندی خود در \fB~/.radicle/config.json\fP، زیر فیلد
\fB"connect"\fP اضافه کنید.
.sp
اکنون که به شبکه متصل شده‌اید، می‌توانیم کلون کردن مخزنی را که روی Radicle
میزبانی می‌شود امتحان کنیم.
.SS "کلون کردن مخزن (Cloning a repository)"
.sp
برای کلون کردن یک مخزن از شبکه Radicle، باید به یک سید (seed) متصل باشید که
میزبان مخزن است. در نهایت، این امر ضروری نخواهد بود، اما در حال حاضر، اتصال
مستقیم با سیدی که از آن کلون می‌کنید الزامی است. پس از برقراری اتصال، می‌توانید
با ارائه یک شناسه مخزن (RID)، دستور \fBrad clone\fP را برای کلون کردن یک مخزن
اجرا کنید. شناسه‌های RID در واقع URNهای منحصربه‌فرد جهانی هستند که یک مخزن را در
Radicle مشخص می‌کنند. برای مثال، بیایید مخزن heartwood در Radicle را کلون کنیم:
.sp
.if n .RS 4
.nf
.fam C
$ rad clone rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5
.fam
.fi
.if n .RE
.sp
در صورت موفقیت‌آمیز بودن دستور، یک checkout از مخزن در مسیر \fB./heartwood\fP
خواهید داشت، به همراه ریموت تنظیم‌شده \fBrad\fP، که می‌توانید از آن واکشی (pull)
کرده و به آن ارسال (push) نمایید.
.sp
ریموت \fBrad\fP از این نظر خاص است که هنگام واکشی (fetch)، همیشه شاخه
\fIauthoritative\fP (دارای مرجعیت) مخزن را بازمی‌گرداند. این شاخه به عنوان
آخرین کامیت در شاخه پیش‌فرض مخزن تعریف می‌شود که حد نصابی از نمایندگان
(delegates) آن را منتشر کرده باشند.
.sp
در پشت صحنه، دستور \fBclone\fP چند کار مهم را انجام می‌دهد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
مشترک دریافت به‌روزرسانی‌ها از این مخزن می‌شود؛ به این فرایند \fItracking\fP (ردیابی) می‌گویند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
یک رونوشت از مخزن را در فضای ذخیره‌سازی محلی شما ایجاد می‌کند، که یک نسخه تکثیرشده (replica) در اختیار شبکه قرار می‌دهد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
یک ریموت Git برای هر \fIdelegate\fP (نماینده) مخزن ایجاد می‌کند. این افراد معمولاً نگه‌دارندگان مخزن هستند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
یک فورک (fork) از مخزن ایجاد می‌کند که تحت کلید عمومی شما قرار دارد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
یک ریموت \fBrad\fP ایجاد می‌کند که می‌توانید برای به‌روزرسانی فورک خود، تغییرات را به آن push کنید.
.RE
.sp
می‌توانید تمام مخازن تکثیرشده و محلی در دسترس را با دستور زیر مشاهده کنید:
.sp
.if n .RS 4
.nf
.fam C
$ rad ls \-\-all
.fam
.fi
.if n .RE
.sp
به طور پیش‌فرض، گره شما مشترک به‌روزرسانی‌های \fIتمام\fP همتاها خواهد شد. این
رفتار را می‌توان با ارسال \fB\-\-scope followed\fP هنگام کلون کردن تغییر داد. همچنین
می‌توان بعداً از طریق دستور \fBrad seed\fP آن را تغییر داد..SS "انتشار مخزن در Radicle"
.sp
برای انتشار یک مخزن Git موجود در شبکهٔ Radicle، به نسخهٔ کاری
رفته و دستور \fBrad init\fP را اجرا کنید:
.sp
.if n .RS 4
.nf
.fam C
$ cd my\-repo
$ rad init
.fam
.fi
.if n .RE
.sp
از شما خواسته می‌شود یک نام برای مخزن و شاخهٔ پیش‌فرض وارد کنید. پس از
ایجاد مخزن، شناسهٔ مخزن (RID) نمایش داده خواهد شد.
این شناسه را با همکاران خود به اشتراک بگذارید تا بتوانند مخزن شما را شبیه‌سازی (clone) کنند.
.sp
توجه داشته باشید که مخزن جدید شما تنها توسط گره‌هایی بازتولید (replicate) می‌شود
که به آن‌ها متصل هستید و یا خط‌مشی ردیابی باز دارند، یا به شناسهٔ گره (Node ID) شما اعتماد دارند.
.sp
دستور \fBrad init\fP یک ریموت ویژه در نسخهٔ کاری شما به نام
\fBrad\fP ایجاد می‌کند. ارسال (push) به این ریموت، تغییرات را در فضای ذخیره‌سازی
محلی شما و در شبکه منتشر می‌کند.
.sp
می‌توانید اطلاعات مربوط به ریموت \fBrad\fP را با دستور زیر مشاهده کنید:
.sp
.if n .RS 4
.nf
.fam C
$ git remote show rad
.fam
.fi
.if n .RE
.sp
می‌توانید با اجرای دستور زیر از ریشهٔ هر مخزن Git، شناسهٔ مخزن (RID)
را نمایش دهید:
.sp
.if n .RS 4
.nf
.fam C
$ rad .
.fam
.fi
.if n .RE
.sp
همچنین می‌توانید با اجرای دستور زیر بارِ هویت (identity payload) مخزن را که شامل
نام، توضیحات و شاخهٔ پیش‌فرض آن است مشاهده کنید:
.sp
.if n .RS 4
.nf
.fam C
$ rad inspect \-\-payload
.fam
.fi
.if n .RE
.SH "فایل‌ها (FILES)"
.sp
\fB~/.radicle\fP
.RS 4
پوشهٔ خانگی رادیکل (\fIRadicle Home\fP). این مکان پیش‌فرض برای فایل‌های پیکربندی
Radicle، کلیدها و فضای ذخیره‌سازی مخزن است. می‌توان آن را با تنظیم
متغیر محیطی \fBRAD_HOME\fP کنترل کرد.
.RE
.sp
\fB~/.radicle/config.json\fP
.RS 4
فایل پیکربندی پیش‌فرض برای Radicle. برای نمایش مکان دقیق
آن در سیستم خود، می‌توانید از دستور \fBrad self \-\-config\fP استفاده کنید.
.RE
.SH "محیط (ENVIRONMENT)"
.sp
متغیرهای محیطی گوناگونی توسط \fBrad\fP استفاده می‌شوند.
.sp
\fBRAD_HOME\fP
.RS 4
مکان پوشهٔ خانگی Radicle شما را تنظیم می‌کند. در صورت عدم تنظیم، پوشهٔ خانگی
Radicle شما در مسیر \fB~/.radicle\fP قرار خواهد گرفت.
.RE
.sp
\fBRAD_PASSPHRASE\fP
.RS 4
اگر مایلید \fBssh\-agent\fP را دور بزنید، می‌توانید عبارت عبور خود را در این
متغیر محیطی ذخیره کنید. توجه داشته باشید که این کار امن نیست و معادل داشتن
یک کلید محرمانهٔ رمزنگاری‌نشده است.
.RE.SH "نویسنده (AUTHOR)"
.sp
تیم Radicle