'\" t
.\"     Title: rad
.\"    Author: The Radicle Team
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-05-14
.\"    Manual: Radicle CLI Manual
.\"    Source: rad 1.0.0
.\"  Language: English
.\"
.TH "RAD" "1" "2026-05-14" "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 command\-line tooling.
.SH "SYNOPSIS"
.sp
\fBrad\fP *
.SH "DESCRIPTION"
.sp
The Radicle CLI is a set of tools designed for users of the Radicle
peer\-to\-peer code collaboration stack. The CLI provides the ability to manage
Radicle profiles and publish repositories to the Radicle network.
.SH "REQUIREMENTS"
.sp
There are a few important requirements for running the Radicle CLI: first, a
recent version of \fBgit\fP (\fB2.34.0\fP or later) must be installed. You can check
your installation by running \fBgit \-\-version\fP. Second, \fBssh\-agent\fP must be
installed and running. To bypass ssh\-agent, it\(cqs possible to set the
\fBRAD_PASSPHRASE\fP environment variable. See the \fIEnvironment\fP section.
.SH "GETTING STARTED"
.sp
Let\(cqs see how we can setup Radicle and clone a repository from the network.
.sp
Before we start, make sure that the \fBrad\fP binary is available on your system by
running:
.sp
.if n .RS 4
.nf
.fam C
$ rad
.fam
.fi
.if n .RE
.sp
This is the base command and the output will show you all available
sub\-commands.
.SS "Creating a profile"
.sp
When using Radicle for the first time, you have to create a new Radicle
\fIprofile\fP. A profile is simply a cryptographic key pair associated with some
storage space on your local device. Radicle stores everything under the Radicle
\fIhome\fP directory, which defaults to \fB~/.radicle\fP on most systems.
To create your profile, run:
.sp
.if n .RS 4
.nf
.fam C
$ rad auth
.fam
.fi
.if n .RE
.sp
Follow the instructions by entering an alias and a passphrase to protect your
key pair. When you\(cqve completed the steps, your new Radicle \fIDID\fP
(Decentralized Identifier) will be displayed. This identifies your device, as
well as all the code you publish. Share it freely with collaborators. Your
alias is a non\-unique name that is shared across the network to identify your
node. It can always be changed at a later time.
.sp
After running \fBrad auth\fP, you should have a new profile and key pair under your
Radicle home. The key pair is used for identifying peers across the network, as
well as signing code and other artifacts published on the network.
.sp
To avoid having to re\-enter your passphrase every time a signature is required,
\fBrad auth\fP adds your secret key to \fBssh\-agent\fP.
.sp
You can always display the full path to your Radicle home directory using:
.sp
.if n .RS 4
.nf
.fam C
$ rad self \-\-home
.fam
.fi
.if n .RE
.sp
The \fBself\fP sub\-command is useful for querying profile information. You can
run it without any arguments to show all of your profile information, including
your DID:
.sp
.if n .RS 4
.nf
.fam C
$ rad self
.fam
.fi
.if n .RE
.SS "Connecting to the network"
.sp
Radicle is a peer\-to\-peer system. This means that there are no clients or
servers; only \fInodes\fP, and every user has to run their own. This ensures
that there is no single point of failure, and the Radicle network can keep on
existing as long as there are users to run nodes.
.sp
The Radicle node is a lightweight process that runs in the background and
manages connections with other nodes, as well as data replication. To check your
node\(cqs status, run:
.sp
.if n .RS 4
.nf
.fam C
$ rad node status
.fam
.fi
.if n .RE
.sp
If the node is not running, you can start it with:
.sp
.if n .RS 4
.nf
.fam C
$ rad node start
.fam
.fi
.if n .RE
.sp
This will start the node in the foreground. Simply add \fB\-\-daemon\fP to run the
node in the background.
.sp
When daemonized, the node will log all output to a file under your Radicle home.
On most systems, this will be \fB~/.radicle/node/node.log\fP.
.sp
You can also display the latest logs at any time using:
.sp
.if n .RS 4
.nf
.fam C
$ rad node logs
.fam
.fi
.if n .RE
.sp
After your node starts, it will attempt to connect to peers on the network.
.sp
Note that if you set up your node to be started using \fBsystemd\fP(1),
the logs will go to the system journal. These can be viewed with \fBjournalctl\fP(1):
.sp
.if n .RS 4
.nf
.fam C
$ journalctl \-u radicle\-node \-S today
.fam
.fi
.if n .RE
.sp
To connect to a specific peer, the \fBconnect\fP sub\-command can be used:
For example, to connect to a community node, you can run:
.sp
.if n .RS 4
.nf
.fam C
$ rad node connect z6MkrLMMsiPWUcNPHcRajuMi9mDfYckSoJyPwwnknocNYPm7@iris.radicle.xyz:8776
.fam
.fi
.if n .RE
.sp
The argument given to \fBconnect\fP is called a node \fIaddress\fP. It is composed of
a Node ID (NID), followed by an \fB@\fP symbol, and the \fIhost\fP name and \fIport\fP.
You can display your NID with \fBrad node status\fP.
.sp
To make these connections permanent, such that they are always tried on
startup, add the addresses to your configuration file at
\fB~/.radicle/config.json\fP, under the \fB"connect"\fP field.
.sp
Now that you\(cqre connected to the network, we can try to clone a repository
hosted on Radicle.
.SS "Cloning a repository"
.sp
To clone a repository from the Radicle network, you need to be connected to a
seed which is hosting the repository. Eventually, this won\(cqt be necessary,
but for now, a direct connection with the seed you are cloning from is
required. Once the connection is established, you can run the \fBrad clone\fP
command to clone a repository, by supplying a Repository Identifier (RID).
RIDs are globally unique URNs that identify a repository on Radicle.
For example, let\(cqs clone the Radicle heartwood repository:
.sp
.if n .RS 4
.nf
.fam C
$ rad clone rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5
.fam
.fi
.if n .RE
.sp
If the command succeeds, you will have a checkout of the repository under
\fB./heartwood\fP, with a \fBrad\fP remote setup, which you can pull from and push to.
.sp
The \fBrad\fP remote is special in that it will always return the \fIauthoritative\fP
branch of the repo, when fetched from. This is defined as the latest commit
on the repository\(cqs default branch that a threshold of delegates have published.
.sp
Under the hood, the \fBclone\fP command does a few important things:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
It subscribes to updates from this repository; this is called \fItracking\fP.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
It creates a copy of the repository under your local storage, which provides
a replica to the network.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
It creates a Git remote for every repository \fIdelegate\fP. These are usually
the repository maintainers.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
It creates a fork of the repository that is under your public key.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
It creates a \fBrad\fP remote which you can push to, to update your fork.
.RE
.sp
You can see all replicated and locally\-available repositories using:
.sp
.if n .RS 4
.nf
.fam C
$ rad ls \-\-all
.fam
.fi
.if n .RE
.sp
By default, your node will subscribe to updates from \fIall\fP peers. This
behavior can be changed by passing \fB\-\-scope followed\fP when cloning. It can
also be changed later via the \fBrad seed\fP command.
.SS "Publishing a repository on Radicle"
.sp
To publish an existing Git repository on the Radicle network, navigate to
a working copy and run the \fBrad init\fP command:
.sp
.if n .RS 4
.nf
.fam C
$ cd my\-repo
$ rad init
.fam
.fi
.if n .RE
.sp
You will be prompted to enter a repository name and default branch. Once the
repository is created, the Repository Identifier (RID) will be printed.
Share this with collaborators so that they can clone your repository.
.sp
Note that your new repository will only be replicated by nodes that you are
connected to and either have an open tracking policy, or trust your Node ID.
.sp
The \fBrad init\fP command creates a special remote in your working copy named
\fBrad\fP. Pushing to this remote publishes changes to your local storage and to
the network.
.sp
You can view information about the \fBrad\fP remote with:
.sp
.if n .RS 4
.nf
.fam C
$ git remote show rad
.fam
.fi
.if n .RE
.sp
You can display the Repository ID (RID) from the root of any Git repository
by running:
.sp
.if n .RS 4
.nf
.fam C
$ rad .
.fam
.fi
.if n .RE
.sp
You can also show the repository\(cqs identity payload, which contains its name,
description and default branch by running:
.sp
.if n .RS 4
.nf
.fam C
$ rad inspect \-\-payload
.fam
.fi
.if n .RE
.SH "FILES"
.sp
\fB~/.radicle\fP
.RS 4
The \fIRadicle Home\fP. This is the default location for Radicle configuration
files, keys, and repository storage. Can be controlled by setting the
\fBRAD_HOME\fP environment variable.
.RE
.sp
\fB~/.radicle/config.json\fP
.RS 4
The default configuration file for Radicle. To display its exact
location on your system, you can use the \fBrad self \-\-config\fP command.
.RE
.SH "ENVIRONMENT"
.sp
Various environment variables are used by \fBrad\fP.
.sp
\fBRAD_HOME\fP
.RS 4
This sets the location of your Radicle home. If unset, your Radicle home will
be located at \fB~/.radicle\fP.
.RE
.sp
\fBRAD_PASSPHRASE\fP
.RS 4
If you would like to bypass \fBssh\-agent\fP, you can store your passphrase in this
environment variable. Note that this is not secure and is equivalent to having
an unencrypted secret key.
.RE
.SH "AUTHOR"
.sp
The Radicle Team