1  .TH "RAD" "1" "2025-09-23" "rad 1.0.0" "Radicle CLI Manual"
  2  .ie \n(.g .ds Aq \(aq
  3  .el       .ds Aq '
  4  .ss \n[.ss] 0
  5  .nh
  6  .ad l
  7  .de URL
  8  \fI\\$2\fP <\\$1>\\$3
  9  ..
 10  .als MTO URL
 11  .if \n[.g] \{\
 12  .  mso www.tmac
 13  .  am URL
 14  .    ad l
 15  .  .
 16  .  am MTO
 17  .    ad l
 18  .  .
 19  .  LINKSTYLE blue R < >
 20  .\}
 21  .SH "NAME"
 22  rad \- Radicle command\-line tooling.
 23  .SH "SYNOPSIS"
 24  .sp
 25  \fBrad\fP *
 26  .SH "DESCRIPTION"
 27  .sp
 28  The Radicle CLI is a set of tools designed for users of the Radicle
 29  peer\-to\-peer code collaboration stack. The CLI provides the ability to manage
 30  Radicle profiles and publish repositories to the Radicle network.
 31  .SH "REQUIREMENTS"
 32  .sp
 33  There are a few important requirements for running the Radicle CLI: first, a
 34  recent version of \fBgit\fP (\fB2.34.0\fP or later) must be installed. You can check
 35  your installation by running \fBgit \-\-version\fP. Second, \fBssh\-agent\fP must be
 36  installed and running. To bypass ssh\-agent, it\(cqs possible to set the
 37  \fBRAD_PASSPHRASE\fP environment variable. See the \fIEnvironment\fP section.
 38  .SH "GETTING STARTED"
 39  .sp
 40  Let\(cqs see how we can setup Radicle and clone a repository from the network.
 41  .sp
 42  Before we start, make sure that the \fBrad\fP binary is available on your system by
 43  running:
 44  .sp
 45  .if n .RS 4
 46  .nf
 47  .fam C
 48  $ rad
 49  .fam
 50  .fi
 51  .if n .RE
 52  .sp
 53  This is the base command and the output will show you all available
 54  sub\-commands.
 55  .SS "Creating a profile"
 56  .sp
 57  When using Radicle for the first time, you have to create a new Radicle
 58  \fIprofile\fP. A profile is simply a cryptographic key pair associated with some
 59  storage space on your local device. Radicle stores everything under the Radicle
 60  \fIhome\fP directory, which defaults to \fB~/.radicle\fP on most systems.
 61  To create your profile, run:
 62  .sp
 63  .if n .RS 4
 64  .nf
 65  .fam C
 66  $ rad auth
 67  .fam
 68  .fi
 69  .if n .RE
 70  .sp
 71  Follow the instructions by entering an alias and a passphrase to protect your
 72  key pair. When you\(cqve completed the steps, your new Radicle \fIDID\fP
 73  (Decentralized Identifier) will be displayed. This identifies your device, as
 74  well as all the code you publish. Share it freely with collaborators. Your
 75  alias is a non\-unique name that is shared across the network to identify your
 76  node. It can always be changed at a later time.
 77  .sp
 78  After running \fBrad auth\fP, you should have a new profile and key pair under your
 79  Radicle home. The key pair is used for identifying peers across the network, as
 80  well as signing code and other artifacts published on the network.
 81  .sp
 82  To avoid having to re\-enter your passphrase every time a signature is required,
 83  \fBrad auth\fP adds your secret key to \fBssh\-agent\fP.
 84  .sp
 85  You can always display the full path to your Radicle home directory using:
 86  .sp
 87  .if n .RS 4
 88  .nf
 89  .fam C
 90  $ rad self \-\-home
 91  .fam
 92  .fi
 93  .if n .RE
 94  .sp
 95  The \fBself\fP sub\-command is useful for querying profile information. You can
 96  run it without any arguments to show all of your profile information, including
 97  your DID:
 98  .sp
 99  .if n .RS 4
100  .nf
101  .fam C
102  $ rad self
103  .fam
104  .fi
105  .if n .RE
106  .SS "Connecting to the network"
107  .sp
108  Radicle is a peer\-to\-peer system. This means that there are no clients or
109  servers; only \fInodes\fP, and every user has to run their own. This ensures
110  that there is no single point of failure, and the Radicle network can keep on
111  existing as long as there are users to run nodes.
112  .sp
113  The Radicle node is a lightweight process that runs in the background and
114  manages connections with other nodes, as well as data replication. To check your
115  node\(cqs status, run:
116  .sp
117  .if n .RS 4
118  .nf
119  .fam C
120  $ rad node status
121  .fam
122  .fi
123  .if n .RE
124  .sp
125  If the node is not running, you can start it with:
126  .sp
127  .if n .RS 4
128  .nf
129  .fam C
130  $ rad node start
131  .fam
132  .fi
133  .if n .RE
134  .sp
135  This will start the node in the foreground. Simply add \fB\-\-daemon\fP to run the
136  node in the background.
137  .sp
138  When daemonized, the node will log all output to a file under your Radicle home.
139  On most systems, this will be \fB~/.radicle/node/node.log\fP.
140  .sp
141  You can also display the latest logs at any time using:
142  .sp
143  .if n .RS 4
144  .nf
145  .fam C
146  $ rad node logs
147  .fam
148  .fi
149  .if n .RE
150  .sp
151  After your node starts, it will attempt to connect to peers on the network.
152  .sp
153  Note that if you set up your node to be started using \fBsystemd\fP(1),
154  the logs will go to the system journal. These can be viewed with \fBjournalctl\fP(1):
155  .sp
156  .if n .RS 4
157  .nf
158  .fam C
159  $ journalctl \-u radicle\-node \-S today
160  .fam
161  .fi
162  .if n .RE
163  .sp
164  To connect to a specific peer, the \fBconnect\fP sub\-command can be used:
165  For example, to connect to a community node, you can run:
166  .sp
167  .if n .RS 4
168  .nf
169  .fam C
170  $ rad node connect z6MkrLMMsiPWUcNPHcRajuMi9mDfYckSoJyPwwnknocNYPm7@iris.radicle.xyz:8776
171  .fam
172  .fi
173  .if n .RE
174  .sp
175  The argument given to \fBconnect\fP is called a node \fIaddress\fP. It is composed of
176  a Node ID (NID), followed by an \fB@\fP symbol, and the \fIhost\fP name and \fIport\fP.
177  You can display your NID with \fBrad node status\fP.
178  .sp
179  To make these connections permanent, such that they are always tried on
180  startup, add the addresses to your configuration file at
181  \fB~/.radicle/config.json\fP, under the \fB"connect"\fP field.
182  .sp
183  Now that you\(cqre connected to the network, we can try to clone a repository
184  hosted on Radicle.
185  .SS "Cloning a repository"
186  .sp
187  To clone a repository from the Radicle network, you need to be connected to a
188  seed which is hosting the repository. Eventually, this won\(cqt be necessary,
189  but for now, a direct connection with the seed you are cloning from is
190  required. Once the connection is established, you can run the \fBrad clone\fP
191  command to clone a repository, by supplying a Repository Identifier (RID).
192  RIDs are globally unique URNs that identify a repository on Radicle.
193  For example, let\(cqs clone the Radicle heartwood repository:
194  .sp
195  .if n .RS 4
196  .nf
197  .fam C
198  $ rad clone rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5
199  .fam
200  .fi
201  .if n .RE
202  .sp
203  If the command succeeds, you will have a checkout of the repository under
204  \fB./heartwood\fP, with a \fBrad\fP remote setup, which you can pull from and push to.
205  .sp
206  The \fBrad\fP remote is special in that it will always return the \fIauthoritative\fP
207  branch of the repo, when fetched from. This is defined as the latest commit
208  on the repository\(cqs default branch that a threshold of delegates have published.
209  .sp
210  Under the hood, the \fBclone\fP command does a few important things:
211  .sp
212  .RS 4
213  .ie n \{\
214  \h'-04'\(bu\h'+03'\c
215  .\}
216  .el \{\
217  .  sp -1
218  .  IP \(bu 2.3
219  .\}
220  It subscribes to updates from this repository; this is called \fItracking\fP.
221  .RE
222  .sp
223  .RS 4
224  .ie n \{\
225  \h'-04'\(bu\h'+03'\c
226  .\}
227  .el \{\
228  .  sp -1
229  .  IP \(bu 2.3
230  .\}
231  It creates a copy of the repository under your local storage, which provides
232  a replica to the network.
233  .RE
234  .sp
235  .RS 4
236  .ie n \{\
237  \h'-04'\(bu\h'+03'\c
238  .\}
239  .el \{\
240  .  sp -1
241  .  IP \(bu 2.3
242  .\}
243  It creates a Git remote for every repository \fIdelegate\fP. These are usually
244  the repository maintainers.
245  .RE
246  .sp
247  .RS 4
248  .ie n \{\
249  \h'-04'\(bu\h'+03'\c
250  .\}
251  .el \{\
252  .  sp -1
253  .  IP \(bu 2.3
254  .\}
255  It creates a fork of the repository that is under your public key.
256  .RE
257  .sp
258  .RS 4
259  .ie n \{\
260  \h'-04'\(bu\h'+03'\c
261  .\}
262  .el \{\
263  .  sp -1
264  .  IP \(bu 2.3
265  .\}
266  It creates a \fBrad\fP remote which you can push to, to update your fork.
267  .RE
268  .sp
269  You can see all replicated and locally\-available repositories using:
270  .sp
271  .if n .RS 4
272  .nf
273  .fam C
274  $ rad ls \-\-all
275  .fam
276  .fi
277  .if n .RE
278  .sp
279  By default, your node will subscribe to updates from \fIall\fP peers. This
280  behavior can be changed by passing \fB\-\-scope followed\fP when cloning. It can
281  also be changed later via the \fBrad seed\fP command.
282  .SS "Publishing a repository on Radicle"
283  .sp
284  To publish an existing Git repository on the Radicle network, navigate to
285  a working copy and run the \fBrad init\fP command:
286  .sp
287  .if n .RS 4
288  .nf
289  .fam C
290  $ cd my\-repo
291  $ rad init
292  .fam
293  .fi
294  .if n .RE
295  .sp
296  You will be prompted to enter a repository name and default branch. Once the
297  repository is created, the Repository Identifier (RID) will be printed.
298  Share this with collaborators so that they can clone your repository.
299  .sp
300  Note that your new repository will only be replicated by nodes that you are
301  connected to and either have an open tracking policy, or trust your Node ID.
302  .sp
303  The \fBrad init\fP command creates a special remote in your working copy named
304  \fBrad\fP. Pushing to this remote publishes changes to your local storage and to
305  the network.
306  .sp
307  You can view information about the \fBrad\fP remote with:
308  .sp
309  .if n .RS 4
310  .nf
311  .fam C
312  $ git remote show rad
313  .fam
314  .fi
315  .if n .RE
316  .sp
317  You can display the Repository ID (RID) from the root of any Git repository
318  by running:
319  .sp
320  .if n .RS 4
321  .nf
322  .fam C
323  $ rad .
324  .fam
325  .fi
326  .if n .RE
327  .sp
328  You can also show the repository\(cqs identity payload, which contains its name,
329  description and default branch by running:
330  .sp
331  .if n .RS 4
332  .nf
333  .fam C
334  $ rad inspect \-\-payload
335  .fam
336  .fi
337  .if n .RE
338  .SH "FILES"
339  .sp
340  \fB~/.radicle\fP
341  .RS 4
342  The \fIRadicle Home\fP. This is the default location for Radicle configuration
343  files, keys, and repository storage. Can be controlled by settting the
344  \fBRAD_HOME\fP environment variable.
345  .RE
346  .sp
347  \fB~/.radicle/config.json\fP
348  .RS 4
349  The default configuration file for Radicle. To display its exact
350  location on your system, you can use the \fBrad self \-\-config\fP command.
351  .RE
352  .SH "ENVIRONMENT"
353  .sp
354  Various environment variables are used by \fBrad\fP.
355  .sp
356  \fBRAD_HOME\fP
357  .RS 4
358  This sets the location of your Radicle home. If unset, your Radicle home will
359  be located at \fB~/.radicle\fP.
360  .RE
361  .sp
362  \fBRAD_PASSPHRASE\fP
363  .RS 4
364  If you would like to bypass \fBssh\-agent\fP, you can store your passphrase in this
365  environment variable. Note that this is not secure and is equivalent to having
366  an unencrypted secret key.
367  .RE
368  .SH "AUTHOR"
369  .sp
370  The Radicle Team