RAD(1)

📦 version 1.10.3, in arch rolling

🌸 RAD(1) — the Radicle CLI manual, but make it make sense 🌸

okay so this is the manual page for rad, a.k.a. the Radicle command-line tooling — that's the whole manual name, we're folding it in right here at the top like a little intro. welcome bestie, let's get you on the network 💅

✨ SYNOPSIS ✨

rad *

that's it. that's the synopsis. iconic, honestly.

💖 DESCRIPTION 💖

The Radicle CLI is a whole set of tools made for users of the Radicle peer-to-peer code collaboration stack. like, the vibe is: the CLI gives you the ability to manage Radicle profiles and publish repositories to the Radicle network. both things. it does both. 🫶

🎀 REQUIREMENTS 🎀

okay so before you can even run the Radicle CLI there are a few important requirements, no cap:

  • first off, a recent version of git (2.34.0 or later) must be installed. you can check your installation by running git --version — super easy, go do it 💖
  • second, ssh-agent must be installed and running. if you wanna bypass ssh-agent, it's possible to set the RAD_PASSPHRASE environment variable instead. see the Environment section bestie, it's right down there ⬇️

🦋 GETTING STARTED 🦋

let's see how we can setup Radicle and clone a repository from the network. so exciting, I'm obsessed already ✨

before we start, make sure that the rad binary is available on your system by running:

$ rad

this is the base command, and the output will show you all available sub-commands. a whole menu of possibilities, literally 🌈

🌸 Creating a profile 🌸

when using Radicle for the first time, you have to create a new Radicle profile. and like — a profile is simply a cryptographic key pair associated with some storage space on your local device. that's it. that's the profile.

Radicle stores everything under the Radicle home directory, which defaults to ~/.radicle on most systems. to create your profile, run:

$ rad auth

follow the instructions by entering an alias and a passphrase to protect your key pair. when you've completed the steps, your new Radicle DID (Decentralized Identifier) will be displayed. this identifies your device, as well as all the code you publish. share it freely with collaborators, it's yours, it's giving main character energy 👑

your alias is a non-unique name that's shared across the network to identify your node. and good news — it can always be changed at a later time, so no stress 🫶

after running rad auth, 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. multi-purpose king 💅

to avoid having to re-enter your passphrase every time a signature is required, rad auth adds your secret key to ssh-agent. so convenient, we love her.

you can always display the full path to your Radicle home directory using:

$ rad self --home

the self 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:

$ rad self

look at all that info. so much self-knowledge 🪞

🌈 Connecting to the network 🌈

Radicle is a peer-to-peer system. this means there are no clients or servers — only nodes, 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. resilient queen behavior, fr fr 💀✨

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's status, run:

$ rad node status

if the node is not running, you can start it with:

$ rad node start

this will start the node in the foreground. simply add --daemon to run the node in the background. background node = introvert node, valid 🧚

when daemonized, the node will log all output to a file under your Radicle home. on most systems, this will be ~/.radicle/node/node.log — noted, bestie 📝

you can also display the latest logs at any time using:

$ rad node logs

after your node starts, it will attempt to connect to peers on the network. making friends, one connection at a time 🫶

note: if you set up your node to be started using systemd(1), the logs will go to the system journal instead. these can be viewed with journalctl(1):
$ journalctl -u radicle-node -S today

to connect to a specific peer, the connect sub-command can be used. for example, to connect to a community node, you can run:

$ rad node connect z6MkrLMMsiPWUcNPHcRajuMi9mDfYckSoJyPwwnknocNYPm7@iris.radicle.network:8776

the argument given to connect is called a node address. it's composed of a Node ID (NID), followed by an @ symbol, and the host name and port. and you can display your own NID with rad node status 💖

to make these connections permanent — such that they are always tried on startup — add the addresses to your configuration file at ~/.radicle/config.json, under the "connect" field. permanent connections, we love commitment 🌸

now that you're connected to the network, we can try to clone a repository hosted on Radicle. let's goooo 🚀

💜 Cloning a repository 💜

to clone a repository from the Radicle network, you need to be connected to a seed which is hosting the repository. eventually, this won't be necessary, but for now, a direct connection with the seed you are cloning from is required. it's giving "temporary but mandatory" 😭

once the connection is established, you can run the rad clone 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's clone the Radicle heartwood repository:

$ rad clone rad:z3gqcJUoA1n9HaHKufZs5FCSGazv5

if the command succeeds, you will have a checkout of the repository under ./heartwood, with a rad remote setup, which you can pull from and push to. slay 💅

the rad remote is special in that it will always return the authoritative branch of the repo when fetched from. this is defined as the latest commit on the repository's default branch that a threshold of delegates have published. the whole gang has to agree, basically 👑

under the hood, the clone command does a few important things:

  • it subscribes to updates from this repository — this is called tracking
  • it creates a copy of the repository under your local storage, which provides a replica to the network
  • it creates a Git remote for every repository delegate. these are usually the repository maintainers
  • it creates a fork of the repository that is under your public key
  • it creates a rad remote which you can push to, to update your fork

so much happening behind the scenes, ngl I'm impressed 😭✨

you can see all replicated and locally-available repositories using:

$ rad ls --all

by default, your node will subscribe to updates from all peers. this behavior can be changed by passing --scope followed when cloning. it can also be changed later via the rad seed command. flexible, we stan 🎀

👑 Publishing a repository on Radicle 👑

to publish an existing Git repository on the Radicle network, navigate to a working copy and run the rad init command:

$ cd my-repo
$ rad init

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. go off, share your code, be generous 🫶

note: 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. so like, make connections, bestie. it's a whole social thing 💀

the rad init command creates a special remote in your working copy named rad. pushing to this remote publishes changes to your local storage and to the network. two birds, one push ✨

you can view information about the rad remote with:

$ git remote show rad

you can display the Repository ID (RID) from the root of any Git repository by running:

$ rad .

yes, just a dot. minimalist, iconic, no notes 💅

you can also show the repository's identity payload — which contains its name, description and default branch — by running:

$ rad inspect --payload

peek behind the curtain, you're allowed 🦋

🍓 FILES 🍓

  • ~/.radicle — the Radicle Home. this is the default location for Radicle configuration files, keys, and repository storage. can be controlled by setting the RAD_HOME environment variable.
  • ~/.radicle/config.json — the default configuration file for Radicle. to display its exact location on your system, you can use the rad self --config command.

🧚 ENVIRONMENT 🧚

various environment variables are used by rad. let's meet them 🫶

  • RAD_HOME — this sets the location of your Radicle home. if unset, your Radicle home will be located at ~/.radicle.
  • RAD_PASSPHRASE — if you would like to bypass ssh-agent, you can store your passphrase in this environment variable. note that this is not secure and is equivalent to having an unencrypted secret key. ⚠️ like, genuinely, heads up — not secure, bestie, do not do this casually 😭

💀 AUTHOR 💀

The Radicle Team 🫶

and that's the whole manual!! this page is from rad 1.0.0, dated 2026-09-10 — so go forth, rad auth, connect to some peers, and publish something iconic. iykyk 🌟💖🎀

📦 where this page comes from