RAD-ID(1)

📦 version 1.10.3, in arch rolling

💅 rad-id ✨

okay so bestie, welcome to rad-id — that's section 1 of the Radicle CLI Manual, and it's literally the glow-up department for your repo's identity 🎀

🌸 NAME 🌸

rad-id — manage changes to a Radicle repository's identity. yes, identity. it's giving main character energy for your repo 🫶

🦋 SYNOPSIS 🦋

rad id [<option>...]
rad id list [<option>...]
rad id update [--title <string>] [--description <string>] <option>...
rad id edit <revision-id> [--title <string>] [--description <string>]
[<option>...]
rad id show <revision-id> [<option>...]
rad id accept | reject <revision-id> [<option>...]
rad id redact <revision-id> [<option>...]

✨ DESCRIPTION ✨

so rad id is the command you use to manage and propose changes to the identity of a Radicle repository. every repo has an identity document attached to it — it's like the repo's lil profile page, containing metadata like the repository name, description, and delegates 💖

the identity document is versioned, and changes to it have to be signed off by a quorum of delegates. no sneaky solo edits, periodt 👑

also: the identity document is stored as a Canonical JSON document. fancy. iconic. keep that in mind, iykyk 💅

🌈 COMMANDS 🌈

run rad id with no arguments and it defaults to the list command, showing you the list of revisions to the identity of the current repository. easy ✨

🍓 list

lists all revisions to the identity document. that's it, that's the vibe.

🧚 update

proposes a new revision to the identity document. revisions have a title and a description in addition to the proposed updated identity document — literally just like source code commits, no cap 💖

if you don't pass a title and description on the command line, you'll get prompted to enter one via your text editor. don't panic, it's fine 🎀

🫶 heads up bestie: if you're the repository's only delegate, proposed changes get automatically accepted and included into the identity document. congrats, you ARE the quorum 💅
  • --title <string> — set the title for the new revision ✍️
  • --description <string> — set the description for the new revision 📝
  • --delegate <did> — update the identity by adding a new delegate, identified by their DID. new friend unlocked 🫶
  • --rescind <did> — update the identity by removing a delegate identified by their DID. bye bestie 😭
  • --threshold <num> — update the identity by setting the number of delegates required to accept a revision 🔢
  • --visibility <private> | <public> — update the identity by setting the repository visibility to private or public 🙈
  • --allow <did> — update the identity by giving a specific peer access to a private repository 🎟️
  • --disallow <did> — update the identity by removing a specific peer's access to a private repository. note that the peer could have the contents of the repository up until the point that access was revoked 👀 (yes, that's a real caveat, be aware)
  • --payload <id> <key> <val> — update the identity by setting metadata in one of the identity payloads. this can be used to update a repository's project name or description, for example. to delete a field from a payload, simply set it to null 🗑️
  • --no-confirm — don't ask for confirmation before creating the revision. skip the "r u sure" text, you're confident 💅
  • --edit — opens your $EDITOR to edit the JSON contents directly 🖊️

💜 edit

edit an existing revision to the identity document. the revision must still be in the "active" state. same options as for update are available ✨

🎀 important distinction, bestie: this edits a proposed revision to the identity. to edit the identity document itself, use update. two different things, don't mix them up 🙈

⭐ show

show a specific revision of the identity document. peek behind the curtain 👑

🌸 accept

accept a proposed revision to the identity document. the revision must be in the "active" state and the caller must be a delegate ✅

🌺 reject

reject a proposed revision to the identity document. the revision must be in the "active" state and the caller must be a delegate ❌

🦋 redact

redact an existing revision to the identity document. the revision must not be in the "accepted" state, and the caller must be the author of the revision. so basically: your revision, your redaction rights 🫶

🎀 OPTIONS 🎀

  • --repo <rid> — specify the repository to operate on. defaults to the current repository 📁
  • --quiet, -q — suppress output. shhh 🤫
  • --help — print help information. classic 🫶

🔥 EXAMPLES 🔥

💖 Adding a delegate

to add a new delegate to a repository and update the threshold, use the update command:

$ rad id update --title "Add Bob" --description "Add Bob as a delegate" \
    --delegate did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk \
    --threshold 2

this creates a new revision proposing to add the delegate identified by the given DID and set the threshold to 2 — meaning two delegates must sign off on future identity changes. two votes minimum, periodt ✌️

🙈 Changing repository visibility

to change a repository from public to private:

$ rad id update --visibility private

note that this will require acceptance from a quorum of delegates to take effect. you can't just flip the switch alone bestie 😭

🍓 Changing a repository payload

to change a repository's name and description, this is usually done through the xyz.radicle.project payload:

$ rad id update --title "Update title and description" \
    --description "Improve clarity" \
    --payload xyz.radicle.project name '"radicle-beans"' \
    --payload xyz.radicle.project description '"Tasty Radicle beans"'
🌈 note that the values passed to --payload, eg. "radicle-beans", must be valid JSON values. this means that strings should be double quoted, as in the example above. yes double. inside the single quotes. it's giving nesting doll energy but that's the rule 💅

🦋 Removing a delegate

to remove a delegate and update the threshold, use the --rescind option:

$ rad id update --title "Remove Bob" \
    --description "Bob is no longer a delegate" \
    --rescind did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk \
    --threshold 1

as with adding a delegate, this change will require approval from the remaining delegates. make sure you set an appropriate new threshold when removing delegates! 🫶 seriously, don't leave it vibing at a number that no longer makes sense 😭

⭐ Adding Canonical References Rules

to update the canonical reference rules of the project, use the --payload xyz.radicle.crefs option while updating, rules as the key, and the rules object as the value. here's an example below:

$ rad id update --title "Update canonical reference rules" \
    --payload xyz.radicle.crefs rules '{
          "refs/heads/master": { "threshold": 1, "allow": "delegates" },
          "refs/tags/*": { "threshold": 2, "allow": "delegates" },
          "refs/tags/qa/*": { "threshold": 1, "allow": "delegates" }
      }'

alternatively, you can use the --edit option for the update command and edit the payload directly. here's an example of what that may look like:

{
  "payload": {
    "xyz.radicle.crefs": {
      "rules": {
        "refs/heads/master": {
          "allow": "delegates",
          "threshold": 1
        },
        "refs/tags/*": {
          "allow": "delegates",
          "threshold": 1
        },
        "refs/tags/qa/*": {
          "allow": "delegates",
          "threshold": 1
        }
      }
    },
    "xyz.radicle.project": {
      "defaultBranch": "master",
      "description": "Radicle Heartwood Protocol & Stack",
      "name": "heartwood"
    }
  },
  "delegates": [
    "did:key:z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi"
  ],
  "threshold": 1
}

👑 AUTHOR 👑

The Radicle Team. kings, honestly 💜

and that's the whole page bestie!! this one's from rad version 1.0.0, dated 2026-09-10 — so go forth, manage that identity, and remember: quorum or it didn't happen 💅✨🎀

📦 where this page comes from