radicle

Radicle

Radicle is a decentralized, peer-to-peer code collaboration protocol built on Git. It enables sovereign code hosting using cryptographic identities and a gossip-based network.

Core Concepts

• RID (Repository ID): Globally unique URN, e.g. rad:z31hE1wco9132nedN3mm5qJjyotna
• NID (Node ID): Device identifier on the network
• DID (Decentralized Identifier): Self-sovereign identity, e.g. did:key:z6Mkhp7VU...
• Delegates: Maintainers who can sign and manage repository metadata
• Seeding: Hosting/replicating a repository across the network
• Patches: Git-based collaborative objects (like pull requests) with revision history

Quick Reference

Task	Command
Check identity	rad self
Current repo RID	rad .
Node status	rad node status
Initialize repo	rad init --name "name" --description "desc" --public --no-confirm
Clone	rad clone rad:<RID>
Create patch	git push rad HEAD:refs/patches (set description with rad patch edit)
Update patch	git push --force (on patch branch)
List patches	rad patch list (also --all/--merged/--draft/--archived)
Show patch	rad patch show <PATCH_ID> (--patch to include diff)
Checkout patch	rad patch checkout <PATCH_ID>
Review patch	rad patch review <PATCH_ID> --accept / --reject
Merge patch	git checkout main && git merge <branch> && git push rad main
List issues	rad issue list (also --all/--closed/--solved/--assigned)
Open issue	rad issue open --title "title" --description "desc" --labels "bug ux"
Show issue	rad issue show <ISSUE_ID>
Comment on issue	rad issue comment <ISSUE_ID> --message "text"
Close issue	rad issue state <ISSUE_ID> --closed (also --open/--solved)
Label issue	rad issue label <ISSUE_ID> --add <label> / --delete <label>
Start node	rad node start
Sync	rad sync --announce
Fetch updates	rad sync --fetch
Add remote	rad remote add <NID> --name <alias>
Seed repo	rad seed rad:<RID>

Multiline text (heredoc)

Prose flags (--description, --message, -m, --title) take multiline values via a quoted heredoc — no editor needed. Quote the delimiter ('EOF') so $ and backticks stay literal:

rad issue open --title "Title" --labels discussion --description "$(cat <<'EOF'
First paragraph.

- point one
EOF
)"

Patches are the exception: a patch's title/description can't ride on a git push option — push options must never contain a newline (git's protocol rejects them). Push to open the patch, then set the description with rad patch edit — its -m is an ordinary arg, so the heredoc works (first line = title, rest = body):

git push rad HEAD:refs/patches          # opens the patch
rad patch edit <PATCH_ID> -m "$(cat <<'EOF'
Patch title

Body, independent of the commit message.
EOF
)"

Same -m "$(heredoc)" works for rad patch update/comment and rad patch review -m. For the commit-message-as-description alternative, see references/commands.md.

Flag gotchas

The real flags, so you don't guess or fall back to --help:

• List filters are boolean flags, not --state: rad issue list --closed, rad patch list --merged.
• Add/remove is --add/--delete (not --remove) for issue label, issue assign, patch label, patch assign.
• rad issue open takes --labels and --assignees (space-separated) at creation time.
• rad patch comment takes a REVISION_ID, not a patch ID.

references/commands.md has the full verified flag list — read it instead of running rad <cmd> --help.

Key Workflows

Contribute to a Project

1. rad clone rad:<RID>
2. git checkout -b feature-branch
3. Make changes, commit
4. git push rad HEAD:refs/patches
5. Address feedback: git push --force

Review and Merge

1. rad patch list to see open patches
2. rad patch show <ID> or rad patch checkout <ID>
3. git checkout main && git merge <branch>
4. git push rad main (marks patch as merged)

Private Repository

1. rad init --private
2. rad id update --allow <DID> to grant access
3. rad id update --disallow <DID> to revoke

Mirror to GitHub

If the repo has a GitHub remote, push to both: git push rad main && git push github main. See references/github-mirror.md for automation setup.

Troubleshooting

Node not running: Run rad node start, then rad node status to verify.

Sync issues: Run rad sync --fetch then rad sync status.

Identity problems: Run rad self to check, rad auth to re-authenticate.

Node status symbols: ✓ connected, ! attempted, ✗ disconnected, ↗ outbound, ↘ inbound.

NAT/firewall: "Not configured to listen for inbound connections" is normal. The node still connects outbound and participates fully. Configure port forwarding for inbound.

Prerequisites

rad --version          # Check installation
rad self               # Check identity
rad node status        # Check node

If rad is not installed: https://radicle.xyz/install or curl -sSLf https://radicle.xyz/install | sh

If no identity: rad auth (or non-interactive: echo "" | rad auth --alias "name" --stdin)