'\" t
.\"     Title: rad-id
.\"    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\-ID" "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-id \- Manage changes to a Radicle repository\*(Aqs identity.
.SH "SYNOPSIS"
.sp
\fBrad id\fP [<option>.\|.\|.]
.br
\fBrad id\fP \fIlist\fP [<option>.\|.\|.]
.br
\fBrad id\fP \fIupdate\fP [\-\-title <string>] [\-\-description <string>] <option>.\|.\|.
.br
\fBrad id\fP \fIedit\fP <revision\-id> [\-\-title <string>] [\-\-description <string>] [<option>.\|.\|.]
.br
\fBrad id\fP \fIshow\fP <revision\-id> [<option>.\|.\|.]
.br
\fBrad id\fP \fIaccept\fP | \fIreject\fP <revision\-id> [<option>.\|.\|.]
.br
\fBrad id\fP \fIredact\fP <revision\-id> [<option>.\|.\|.]
.br
.SH "DESCRIPTION"
.sp
The \fBrad id\fP command is used to manage and propose changes to the identity of a
Radicle repository. Each repository has an associated identity document that
contains metadata such as the repository name, description, and delegates. The
identity document is versioned and changes to it must be signed by a quorum of
delegates.
.sp
The identity document is stored as a \fICanonical JSON\fP document.
.SH "COMMANDS"
.sp
With no arguments, \fBrad id\fP defaults to the \fIlist\fP command, showing the list of
revisions to the identity of the current repository.
.SS "list"
.sp
Lists all revisions to the identity document.
.SS "update"
.sp
Proposes a new revision to the identity document. Revisions have a title and a
description in addition to the proposed updated identity document, just like
source code commits.
.sp
If a title and description are not provided on the command line, you will be
prompted to enter one via your text editor.
.sp
Note that if you are the repository\(cqs only delegate, proposed changes will be
automatically accepted and included into the identity document.
.sp
\fB\-\-title\fP \fI<string>\fP
.RS 4
Set the title for the new revision.
.RE
.sp
\fB\-\-description\fP \fI<string>\fP
.RS 4
Set the description for the new revision.
.RE
.sp
\fB\-\-delegate\fP \fI<did>\fP
.RS 4
Update the identity by adding a new delegate, identified by their DID.
.RE
.sp
\fB\-\-rescind\fP \fI<did>\fP
.RS 4
Update the identity by removing a delegate identified by their DID.
.RE
.sp
\fB\-\-threshold\fP \fI<num>\fP
.RS 4
Update the identity by setting the number of delegates required to accept a
revision.
.RE
.sp
\fB\-\-visibility\fP \fI<private>\fP | \fI<public>\fP
.RS 4
Update the identity by setting the repository visibility to private or public.
.RE
.sp
\fB\-\-allow\fP \fI<did>\fP
.RS 4
Update the identity by giving a specific peer access to a private repository.
.RE
.sp
\fB\-\-disallow\fP \fI<did>\fP
.RS 4
Update the identity by removing a specific peer\(cqs access to a private repository.
Note that the peer could have the contents of the repository up until the
point that access was revoked.
.RE
.sp
\fB\-\-payload\fP \fI<id> <key> <val>\fP
.RS 4
Update the identity by setting metadata in one of the identity payloads.
This can be used to update a repository\(cqs project name or description, for
example. To delete a field from a payload, simply set it to \fBnull\fP.
.RE
.sp
\fB\-\-no\-confirm\fP
.RS 4
Don\(cqt ask for confirmation before creating the revision.
.RE
.sp
\fB\-\-edit\fP
.RS 4
Opens your $EDITOR to edit the JSON contents directly.
.RE
.SS "edit"
.sp
Edit an existing revision to the identity document. The revision must still be
in the "active" state. The same options as for \fBupdate\fP are available. Note
that this edits a proposed revision to the identity; to edit the identity
document itself, use \fBupdate\fP.
.SS "show"
.sp
Show a specific revision of the identity document.
.SS "accept"
.sp
Accept a proposed revision to the identity document. The revision must be in
the "active" state and the caller must be a delegate.
.SS "reject"
.sp
Reject a proposed revision to the identity document. The revision must be in
the "active" state and the caller must be a delegate.
.SS "redact"
.sp
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.
.SH "OPTIONS"
.sp
\fB\-\-repo\fP \fI<rid>\fP
.RS 4
Specify the repository to operate on. Defaults to the current repository.
.RE
.sp
\fB\-\-quiet\fP, \fB\-q\fP
.RS 4
Suppress output.
.RE
.sp
\fB\-\-help\fP
.RS 4
Print help information.
.RE
.SH "EXAMPLES"
.SS "Adding a delegate"
.sp
To add a new delegate to a repository and update the threshold, use the
\fBupdate\fP command:
.sp
.if n .RS 4
.nf
.fam C
$ rad id update \-\-title "Add Bob" \-\-description "Add Bob as a delegate" \(rs
    \-\-delegate did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk \(rs
    \-\-threshold 2
.fam
.fi
.if n .RE
.sp
This will create a new revision proposing to add the delegate identified by the
given DID and set the threshold to \f(CR2\fP, meaning two delegates must sign off on
future identity changes.
.SS "Changing repository visibility"
.sp
To change a repository from public to private:
.sp
.if n .RS 4
.nf
.fam C
$ rad id update \-\-visibility private
.fam
.fi
.if n .RE
.sp
Note that this will require acceptance from a quorum of delegates to take
effect.
.SS "Changing a repository payload"
.sp
To change a repository\(cqs name and description, this is usually done through the
\fBxyz.radicle.project\fP payload:
.sp
.if n .RS 4
.nf
.fam C
$ rad id update \-\-title "Update title and description" \(rs
    \-\-description "Improve clarity" \(rs
    \-\-payload xyz.radicle.project name \*(Aq"radicle\-beans"\*(Aq \(rs
    \-\-payload xyz.radicle.project description \*(Aq"Tasty Radicle beans"\*(Aq
.fam
.fi
.if n .RE
.sp
Note that the values passed to \fB\-\-payload\fP, eg. \f(CR"radicle\-beans"\fP must be valid
\fIJSON\fP values. This means that strings should be double quoted, as in the
example above.
.SS "Removing a delegate"
.sp
To remove a delegate and update the threshold, use the \fB\-\-rescind\fP option:
.sp
.if n .RS 4
.nf
.fam C
$ rad id update \-\-title "Remove Bob" \(rs
    \-\-description "Bob is no longer a delegate" \(rs
    \-\-rescind did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk \(rs
    \-\-threshold 1
.fam
.fi
.if n .RE
.sp
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!
.SS "Adding Canonical References Rules"
.sp
To update the canonical reference rules of the project, use the \f(CR\-\-payload
xyz.radicle.crefs\fP option while updating, \f(CRrules\fP as the key, and the rules
object as the value. Here is an example below:
.sp
.if n .RS 4
.nf
.fam C
$ rad id update \-\-title "Update canonical reference rules" \(rs
    \-\-payload xyz.radicle.crefs rules \*(Aq{
          "refs/heads/master": { "threshold": 1, "allow": "delegates" },
          "refs/tags/*": { "threshold": 2, "allow": "delegates" },
          "refs/tags/qa/*": { "threshold": 1, "allow": "delegates" }
      }\*(Aq
.fam
.fi
.if n .RE
.sp
Alternatively, you can use the \f(CR\-\-edit\fP option for the \f(CRupdate\fP command and edit
the payload directly. Here is an example of what that may look like:
.sp
.if n .RS 4
.nf
.fam C
{
  "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
}
.fam
.fi
.if n .RE
.SH "AUTHOR"
.sp
The Radicle Team