1  .TH "RAD\-ID" "1" "2025-09-23" "rad 1.0.0" "Radicle CLI Manual"
  2  .ie \n(.g .ds Aq \(aq
  3  .el       .ds Aq '
  4  .ss \n[.ss] 0
  5  .nh
  6  .ad l
  7  .de URL
  8  \fI\\$2\fP <\\$1>\\$3
  9  ..
 10  .als MTO URL
 11  .if \n[.g] \{\
 12  .  mso www.tmac
 13  .  am URL
 14  .    ad l
 15  .  .
 16  .  am MTO
 17  .    ad l
 18  .  .
 19  .  LINKSTYLE blue R < >
 20  .\}
 21  .SH "NAME"
 22  rad-id \- Manage changes to a Radicle repository\*(Aqs identity.
 23  .SH "SYNOPSIS"
 24  .sp
 25  \fBrad id\fP [<option>...]
 26  .br
 27  \fBrad id\fP \fIlist\fP [<option>...]
 28  .br
 29  \fBrad id\fP \fIupdate\fP [\-\-title <string>] [\-\-description <string>] <option>...
 30  .br
 31  \fBrad id\fP \fIedit\fP <revision\-id> [\-\-title <string>] [\-\-description <string>] [<option>...]
 32  .br
 33  \fBrad id\fP \fIshow\fP <revision\-id> [<option>...]
 34  .br
 35  \fBrad id\fP \fIaccept\fP | \fIreject\fP <revision\-id> [<option>...]
 36  .br
 37  \fBrad id\fP \fIredact\fP <revision\-id> [<option>...]
 38  .br
 39  .SH "DESCRIPTION"
 40  .sp
 41  The \fBrad id\fP command is used to manage and propose changes to the identity of a
 42  Radicle repository. Each repository has an associated identity document that
 43  contains metadata such as the repository name, description, and delegates. The
 44  identity document is versioned and changes to it must be signed by a quorum of
 45  delegates.
 46  .sp
 47  The identity document is stored as a \fICanonical JSON\fP document.
 48  .SH "COMMANDS"
 49  .sp
 50  With no arguments, \fBrad id\fP defaults to the \fIlist\fP command, showing the list of
 51  revisions to the identity of the current repository.
 52  .SS "list"
 53  .sp
 54  Lists all revisions to the identity document.
 55  .SS "update"
 56  .sp
 57  Proposes a new revision to the identity document. Revisions have a title and a
 58  description in addition to the proposed updated identity document, just like
 59  source code commits.
 60  .sp
 61  If a title and description are not provided on the command line, you will be
 62  prompted to enter one via your text editor.
 63  .sp
 64  Note that if you are the repository\(cqs only delegate, proposed changes will be
 65  automatically accepted and included into the identity document.
 66  .sp
 67  \fB\-\-title\fP \fI<string>\fP
 68  .RS 4
 69  Set the title for the new revision.
 70  .RE
 71  .sp
 72  \fB\-\-description\fP \fI<string>\fP
 73  .RS 4
 74  Set the description for the new revision.
 75  .RE
 76  .sp
 77  \fB\-\-delegate\fP \fI<did>\fP
 78  .RS 4
 79  Update the identity by adding a new delegate, identified by their DID.
 80  .RE
 81  .sp
 82  \fB\-\-rescind\fP \fI<did>\fP
 83  .RS 4
 84  Update the identity by removing a delegate identified by their DID.
 85  .RE
 86  .sp
 87  \fB\-\-threshold\fP \fI<num>\fP
 88  .RS 4
 89  Update the identity by setting the number of delegates required to accept a
 90  revision.
 91  .RE
 92  .sp
 93  \fB\-\-visibility\fP \fI<private>\fP | \fI<public>\fP
 94  .RS 4
 95  Update the identity by setting the repository visibility to private or public.
 96  .RE
 97  .sp
 98  \fB\-\-allow\fP \fI<did>\fP
 99  .RS 4
100  Update the identity by giving a specific peer access to a private repository.
101  .RE
102  .sp
103  \fB\-\-disallow\fP \fI<did>\fP
104  .RS 4
105  Update the identity by removing a specific peer\(cqs access to a private repository.
106  Note that the peer could have the contents of the repository up until the
107  point that access was revoked.
108  .RE
109  .sp
110  \fB\-\-payload\fP \fI<id> <key> <val>\fP
111  .RS 4
112  Update the identity by setting metadata in one of the identity payloads.
113  This can be used to update a repository\(cqs project name or description, for
114  example. To delete a field from a payload, simply set it to \fBnull\fP.
115  .RE
116  .sp
117  \fB\-\-no\-confirm\fP
118  .RS 4
119  Don\(cqt ask for confirmation before creating the revision.
120  .RE
121  .sp
122  \fB\-\-edit\fP
123  .RS 4
124  Opens your $EDITOR to edit the JSON contents directly.
125  .RE
126  .SS "edit"
127  .sp
128  Edit an existing revision to the identity document. The revision must still be
129  in the "active" state. The same options as for \fBupdate\fP are available. Note
130  that this edits a proposed revision to the identity; to edit the identity
131  document itself, use \fBupdate\fP.
132  .SS "show"
133  .sp
134  Show a specific revision of the identity document.
135  .SS "accept"
136  .sp
137  Accept a proposed revision to the identity document. The revision must be in
138  the "active" state and the caller must be a delegate.
139  .SS "reject"
140  .sp
141  Reject a proposed revision to the identity document. The revision must be in
142  the "active" state and the caller must be a delegate.
143  .SS "redact"
144  .sp
145  Redact an existing revision to the identity document. The revision must not be
146  in the "accepted" state and the caller must be the author of the revision.
147  .SH "OPTIONS"
148  .sp
149  \fB\-\-repo\fP \fI<rid>\fP
150  .RS 4
151  Specify the repository to operate on. Defaults to the current repository.
152  .RE
153  .sp
154  \fB\-\-quiet\fP, \fB\-q\fP
155  .RS 4
156  Suppress output.
157  .RE
158  .sp
159  \fB\-\-help\fP
160  .RS 4
161  Print help information.
162  .RE
163  .SH "EXAMPLES"
164  .SS "Adding a delegate"
165  .sp
166  To add a new delegate to a repository and update the threshold, use the
167  \fBupdate\fP command:
168  .sp
169  .if n .RS 4
170  .nf
171  .fam C
172  $ rad id update \-\-title "Add Bob" \-\-description "Add Bob as a delegate" \(rs
173      \-\-delegate did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk \(rs
174      \-\-threshold 2
175  .fam
176  .fi
177  .if n .RE
178  .sp
179  This will create a new revision proposing to add the delegate identified by the
180  given DID and set the threshold to \f(CR2\fP, meaning two delegates must sign off on
181  future identity changes.
182  .SS "Changing repository visibility"
183  .sp
184  To change a repository from public to private:
185  .sp
186  .if n .RS 4
187  .nf
188  .fam C
189  $ rad id update \-\-visibility private
190  .fam
191  .fi
192  .if n .RE
193  .sp
194  Note that this will require acceptance from a quorum of delegates to take
195  effect.
196  .SS "Changing a repository payload"
197  .sp
198  To change a repository\(cqs name and description, this is usually done through the
199  \fBxyz.radicle.project\fP payload:
200  .sp
201  .if n .RS 4
202  .nf
203  .fam C
204  $ rad id update \-\-title "Update title and description" \(rs
205      \-\-description "Improve clarity" \(rs
206      \-\-payload xyz.radicle.project name \*(Aq"radicle\-beans"\*(Aq \(rs
207      \-\-payload xyz.radicle.project description \*(Aq"Tasty Radicle beans"\*(Aq
208  .fam
209  .fi
210  .if n .RE
211  .sp
212  Note that the values passed to \fB\-\-payload\fP, eg. \f(CR"radicle\-beans"\fP must be valid
213  \fIJSON\fP values. This means that strings should be double quoted, as in the
214  example above.
215  .SS "Removing a delegate"
216  .sp
217  To remove a delegate and update the threshold, use the \fB\-\-rescind\fP option:
218  .sp
219  .if n .RS 4
220  .nf
221  .fam C
222  $ rad id update \-\-title "Remove Bob" \(rs
223      \-\-description "Bob is no longer a delegate" \(rs
224      \-\-rescind did:key:z6Mkt67GdsW7715MEfRuP4pSZxJRJh6kj6Y48WRqVv4N1tRk \(rs
225      \-\-threshold 1
226  .fam
227  .fi
228  .if n .RE
229  .sp
230  As with adding a delegate, this change will require approval from the remaining
231  delegates. Make sure you set an appropriate new threshold when removing
232  delegates!
233  .SS "Adding Canonical References Rules"
234  .sp
235  To update the canonical reference rules of the project, use the \f(CR\-\-payload
236  xyz.radicle.crefs\fP option while updating, \f(CRrules\fP as the key, and the rules
237  object as the value. Here is an example below:
238  .sp
239  .if n .RS 4
240  .nf
241  .fam C
242  $ rad id update \-\-title "Update canonical reference rules" \(rs
243      \-\-payload xyz.radicle.crefs rules \*(Aq{
244            "refs/heads/master": { "threshold": 1, "allow": "delegates" },
245            "refs/tags/*": { "threshold": 2, "allow": "delegates" },
246            "refs/tags/qa/*": { "threshold": 1, "allow": "delegates" }
247        }\*(Aq
248  .fam
249  .fi
250  .if n .RE
251  .sp
252  Alternatively, you can use the \f(CR\-\-edit\fP option for the \f(CRupdate\fP command and edit
253  the payload directly. Here is an example of what that may look like:
254  .sp
255  .if n .RS 4
256  .nf
257  .fam C
258  {
259    "payload": {
260      "xyz.radicle.crefs": {
261        "rules": {
262          "refs/heads/master": {
263            "allow": "delegates",
264            "threshold": 1
265          },
266          "refs/tags/*": {
267            "allow": "delegates",
268            "threshold": 1
269          },
270          "refs/tags/qa/*": {
271            "allow": "delegates",
272            "threshold": 1
273          }
274        }
275      },
276      "xyz.radicle.project": {
277        "defaultBranch": "master",
278        "description": "Radicle Heartwood Protocol & Stack",
279        "name": "heartwood"
280      }
281    },
282    "delegates": [
283      "did:key:z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi"
284    ],
285    "threshold": 1
286  }
287  .fam
288  .fi
289  .if n .RE
290  .SH "AUTHOR"
291  .sp
292  The Radicle Team