The Traveler's Client

Installing Radicle, cryptographic identity and first steps

Install Radicle (rad)

Radicle is a command-line tool called rad. It is your interface with the peer-to-peer network. Before anything else, you need to install it on your machine.

On Linux

The recommended method uses the official install script:

# Method 1: Official install script
curl -sSf https://radicle.xyz/install | sh

# Method 2: Via Cargo (if you have Rust installed)
cargo install radicle-cli

# Verify the installation
rad --version

The rad binary is installed in ~/.radicle/bin/. Make sure this path is in your PATH:

# Add to PATH (in ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.radicle/bin:$PATH"

On macOS

# Via the official script
curl -sSf https://radicle.xyz/install | sh

# Or via Cargo (if you have Rust installed)
cargo install radicle-cli

# Verify the installation
rad --version

On Windows

Radicle is primarily designed for Linux and macOS. On Windows, you have two options:

# Via WSL (Windows Subsystem for Linux) - only supported method
# In a WSL Ubuntu terminal:
curl -sSf https://radicle.xyz/install | sh

Your cryptographic identity

On GitHub, you have a username and password. On Radicle, it's different. Your identity rests on cryptography - a key pair that proves you are really you, without any server needing to verify it.

Create your identity with rad auth

# Create your Radicle identity
rad auth

# You will see something like:
# Initializing your radicle identity
# Enter a passphrase (or leave blank):
# Your DID is did:key:z6Mki7...
# You're all set!

The rad auth command generates:

• A private key (stored locally in ~/.radicle/keys/) - this is your secret, never share it
• A public key - this is your identity visible to others
• A DID (Decentralized Identifier) - a unique identifier in the format did:key:z6Mk...

Understanding ed25519 keys

Radicle uses the same type of keys as SSH: ed25519. It is a modern, fast and secure digital signature algorithm. Every action you take on Radicle (publish, comment, propose a patch) is cryptographically signed.

This means nobody can impersonate you - even though no central server exists to verify who is who.

The DID - your decentralized identity

The DID (Decentralized Identifier) is a W3C standard. It is a universal way to identify yourself without depending on a provider. Your Radicle DID looks like:

did:key:z6Mki7kFMjfQXbB2tRzpR5oSrQFkAuGhUTnKGVzE8pTo6VDB

This DID is mathematically derived from your public key. It is unique in the world and you are its sole owner.

Initialize a Radicle project

Radicle does not replace Git - it builds on top of it. You always start with a normal Git repository, then add the Radicle layer.

rad init - transform a Git repo into a Radicle project

# Create a normal Git repo
mkdir my-project
cd my-project
git init -b main
echo "# My Project" > README.md
git add README.md
git commit -m "First commit"

# Initialize Radicle in this repo
rad init

# You will see:
# Initializing radicle project in /home/user/my-project
# Name: my-project
# Description: (optional)
# Default branch: main
# Project rad:z2e7R... created.

The rad init command creates a unique project identifier (the rad:z...). It is the decentralized equivalent of a GitHub URL. This identifier is permanent and will never change.

rad inspect - examine a project

# See project details
rad inspect

# Displays:
# Project: my-project
# RID: rad:z2e7R...
# Description: ...
# Default branch: main
# Delegates: did:key:z6Mk... (you)

The Delegates field is important: these are the people authorized to merge patches. When you create a project, you are the sole delegate.

Publish and synchronize

rad push - publish your code to the network

# Publish your repo to the Radicle network
rad push

# The local Radicle node announces your project to peers
# Seeds (always-online nodes) will replicate it

Unlike git push which sends to a specific server, rad push publishes to the peer network. There is no single destination - your code is available to everyone who is connected.

rad sync - synchronize with peers

# Synchronize with connected peers (send and receive updates)
rad sync

rad sync is the equivalent of a decentralized git fetch. It contacts connected peers and exchanges the latest changes. Fetching is included by default.

Clone a project with rad clone

# Clone a Radicle project
rad clone rad:z2e7RaGkMUjH3dMhiKd5dm2E3pCXA

# The clone:
# 1. Contacts peers and seeds hosting this project
# 2. Downloads the Git repo
# 3. Automatically configures Radicle remotes

The rad:z... identifier replaces the GitHub URL. You can share it through any channel - email, messaging, QR code. As long as a connected node has the project, you can clone it.

Patches - Decentralized Pull Requests

On GitHub, you create a Pull Request to propose changes. On Radicle, the equivalent is called a Patch. Same concept, but without a central server.

Create a patch

# 1. Create a branch and make your changes
git switch -c my-feature
echo "New feature" >> README.md
git add README.md
git commit -m "Add a feature"

# 2. Propose a patch
rad patch create

# You will be prompted to enter:
# - A title for the patch
# - A description (optional)
# The patch is signed with your key and published to the network

List and review patches

# List all project patches
rad patch list

# Displays:
# ID       TITLE                    AUTHOR            STATUS
# abc123   Add a feature            did:key:z6Mk...   open

# See patch details
rad patch show abc123

Comment on a patch

# Add a comment to a patch
rad patch comment abc123 --message "Good idea, but can you add tests?"

Merge a patch

# If you are a delegate of the project, you can merge
rad patch merge abc123

# The patch is merged into the default branch
# The action is signed and propagated across the network

Close a patch without merging

# Close a patch (rejected or abandoned)
rad patch close abc123

Decentralized Issues

Radicle also offers a built-in issue system - no external tracker needed.

Create an issue

# Create an issue
rad issue create --title "Bug: config file doesn't load" \
                 --description "When launching the app without config.yaml, it crashes instead of using default values."

List and manage issues

# List open issues
rad issue list

# Comment on an issue
rad issue comment <issue-id> --message "I can reproduce the bug on Linux."

# Close an issue
rad issue close <issue-id>

# Reopen an issue (change its state)
rad issue state <issue-id> open

Like patches, issues are stored in the repository's Radicle data. They travel with the code, from peer to peer.

Comparison - GitHub vs Radicle

Hands-on exercise - First steps with rad

# Create your Radicle identity
rad auth

# Note your DID somewhere - this is your identity

# Create a new repo
mkdir travelers-workshop
cd travelers-workshop
git init -b main

# Create a first file
echo "# Traveler's Workshop" > README.md
echo "My first Radicle project." >> README.md
git add README.md
git commit -m "Initialize the project"

# Initialize Radicle
rad init

# Check project details
rad inspect

# Note the project identifier (RID: rad:z...)

# Create a working branch
git switch -c improve-readme

# Modify the README
echo "" >> README.md
echo "## Features" >> README.md
echo "- Peer-to-peer collaboration" >> README.md
echo "- Cryptographic identity" >> README.md

git add README.md
git commit -m "Add features section"

# Propose a patch
rad patch create

# List your patches
rad patch list

# Go back to main and merge the patch
git switch main
rad patch merge <patch-id>

# Create a test issue
rad issue create --title "Add a CONTRIBUTING file" \
                 --description "We should explain how to contribute to the project."

# List issues
rad issue list

Command summary