# CLI Reference
Full reference for the `rdrop` command-line interface.
> **Tip:** run `rdrop help <subcommand>` for flag details on any command.
---
## `rdrop id`
Print this node's peer-id (its public key in base32). Share it with others so they can add you to their peer address book and to their rings.
```sh
rdrop id
```
---
## `rdrop daemon`
`rdrop` serves blob transfer through a background daemon and listen for CLI commands. Start it once; it keeps running until you stop it.
| `rdrop daemon start` | Start the daemon in the background |
| `rdrop daemon stop` | Stop a running daemon |
| `rdrop daemon status` | Show daemon status and node ID |
### Logging
By default only warnings are printed. Set `RUST_LOG` to get more detail:
```sh
RUST_LOG=ringdrop=info rdrop daemon start # info-level logs for all ringdrop code
RUST_LOG=debug rdrop daemon start # debug logs including iroh internals
```
This applies to every command, not just the daemon.
---
## `rdrop ring`
Manage rings. A ring is a named group of peers; blobs tagged with a ring are downloadable by its members.
| `rdrop ring new <name>` | Create a new ring |
| `rdrop ring list` | List all rings with member counts |
| `rdrop ring add <ring> <peer-id>` | Add a peer to a ring (auto-registers in address book) |
| `rdrop ring remove <ring> <peer-id>` | Remove a peer from a ring |
| `rdrop ring members <ring>` | List members of a ring |
Examples:
```sh
rdrop ring new friends
rdrop ring list
rdrop ring add friends <peer-id>
rdrop ring remove friends <peer-id>
rdrop ring members friends
```
**Notes:**
- `ring add` auto-registers the peer in the local peer address book if not already present. You can use `rdrop peer add <peer-id> --nickname <name>` afterward to assign a nickname.
- The built-in `open` ring has no membership list — any peer can access blobs associated with this special ring.
---
## `rdrop peer`
Manage the local peer address book. Peers registered here can be given human-readable nicknames that appear consistently throughout the other command output.
| `rdrop peer add <peer-id>` | Register a peer; preserves any existing nickname |
| `rdrop peer add <peer-id> --nickname <name>` | Register or rename a peer |
| `rdrop peer list` | List all known peers |
| `rdrop peer remove <peer-id>` | Remove peer from address book, all rings, and all grants |
Examples:
```sh
rdrop peer add <peer-id>
rdrop peer add <peer-id> --nickname alice
rdrop peer add <peer-id> --nickname bob # rename: run again with a different nickname
rdrop peer list
rdrop peer remove <peer-id>
```
**Notes:**
- `peer add` is idempotent: re-running with the same peer and nickname results in no operation.
- `peer add --nickname <name>` updates any existing nickname.
- `peer remove` also removes the peer from every ring and revokes all their catalog grants.
- `peer remove` errors if the peer is not in the address book (consistent with `ring remove` and `grant remove`).
---
## `rdrop import`
Shortcut for `rdrop blob import`. Import a file or directory into the local blob store and print a downloadable ticket.
Examples:
```sh
rdrop import file.txt # untagged — warns until tagged
rdrop import file.txt --open # publicly accessible (anyone with the ticket)
rdrop import file.txt --ring friends # restrict to the "friends" ring
rdrop import file.txt --ring friends --ring work # multiple rings
```
If no `--ring` or `--open` is given, the blob is stored but cannot be downloaded yet (it needstobe associated with a ring orthe `"open"` one). If the file was already imported, the existing ring associations are summarised instead.
---
## `rdrop blob`
Offer blob lifecycle management.
| `rdrop blob import <filename>` | Import and tag a file or directory |
| `rdrop blob list` | List all local blobs with ring tags and tickets |
| `rdrop blob remove <filename\|hash>` | Remove a blob and all its ring associations |
Examples:
```sh
rdrop blob import file.txt --ring friends
rdrop blob list
rdrop blob list --ring friends # filter by ring
rdrop blob list --peer <peer-id> # filter by peer access
rdrop blob remove file.txt
```
---
## `rdrop tag`
Associate an already-imported blob with a ring (or mark it open). Use this to change access after import.
Examples:
```sh
rdrop tag file.txt --ring friends
rdrop tag file.txt --open
```
---
## `rdrop untag`
Remove ring associations from an already-imported blob, revoking access for the affected rings.
| `--ring <name>` | Remove a specific ring (repeatable) |
| `--open` | Revoke public access (removes the open-ring association) |
| `--all` | Remove every ring association; blob becomes inaccessible to all peers |
Exactly one of `--ring`, `--open`, or `--all` must be given; they are mutually exclusive.
Examples:
```sh
rdrop untag <file|hash> --open # make no longer publicly accessible
rdrop untag <hash|hash> --all # revoke all access
```
**Notes:**
- Untagging with `--ring` or `--open` preserves all other ring associations.
- If the blob is not currently tagged with the specified ring, the command exits on error.
- `--all` always succeeds, even if the blob has no ring associations.
---
## `rdrop receive`
Download a blob from an `rdrop://` ticket. Automatically resumes if interrupted — no verified data is re-transferred.
Examples:
```sh
rdrop receive rdrop://ABCDEF...
rdrop receive rdrop://ABCDEF... --dest ./downloads
rdrop receive rdrop://ABCDEF... --dest ./downloads/file.txt
```
`--dest` can be a directory (file is placed inside it) or an explicit file path.
---
## `rdrop grant`
Grant specific rights to remote peers on your local node.
| `rdrop grant add <peer-id> <privilege>` | Grant a privilege to a peer |
| `rdrop grant remove <peer-id> <privilege>` | Revoke a privilege |
| `rdrop grant list` | List all grants |
| `rdrop grant list --peer <peer-id>` | Filter by peer |
| `rdrop grant list --privilege <privilege>` | Filter by privilege |
The only currently defined privilege is `blob-list`. A peer with this privilege can list the blobs they have access to on your node (they only see what their ring membership already allows them to download).
Examples:
```sh
rdrop grant add <peer-id> blob-list
rdrop grant remove <peer-id> blob-list
rdrop grant list
rdrop grant list --peer <peer-id>
rdrop grant list --privilege blob-list
```
---
## `rdrop remote`
Perform a command in a remote node.
| `rdrop remote blob-list <peer-id>` | List blobs accessible to you on a remote node |
The remote must have granted you the `blob-list` privilege (see `rdrop grant add`).
Example:
```sh
rdrop remote blob-list <peer-id>
```
---
## Global flags
| `--data-dir <path>` | Override the data directory (default: `~/.ringdrop`) |
| `--version` | Print version |
| `--help` | Print help |
The data directory can also be set via the `RINGDROP_DATA_DIR` environment variable.