Quickstart
This guide will give you a quick tour of iroh from the command line. We'll create a document and sync it between to terminals. After that we'll look at where to go next to learn about how iroh works & where to integrate into your application.
Iroh is currently in alpha release. We're aiming for Sept. 30th for a proper, production quality release of the same API this quickstart covers.
Install Iroh
The first thing you'll need to do is get the iroh CLI. Follow the instructions on our install guide to install iroh.
Confirm iroh works & is installed correctly by running iroh help
. You should see help text that starts like this:
$ iroh help
Iroh is a tool for syncing bytes.
https://iroh.computer/docs
Usage: iroh [OPTIONS] [COMMAND]
...
Start the iroh console
$ iroh start
Listening addresses:
108.41.41.113:52658
108.41.41.113:11204
192.168.86.28:11204
DERP Region: 1
PeerID: 3pwjma35aeu7mmmjolslefpnlsdztyp4zwf4zwx32nnvlmzko4aa
Now that we have a node running, let's create a document. We'll do that from the console. The console is a REPL that lets you talk to the node. We open the console with iroh console
, connecting to the node we started with iroh start
.
$ iroh console
Welcome to the Iroh console!
Type `help` for a list of commands.
>
Create an Author
Before we can work with documents, we need to create an author, which is an identity that will represent us while we work.
> author new --switch
fhu3uk4wc2hl2e45nepyyic5u2tv37gmnmeoev4ka2bgieqhhz7a
Active author is now fhu3uk4w…
We use the --switch
flag to make this author the default author for the console. This means we don't have to pass the author ID to every command.
Create a Document
Next, let's create a document. Again we'll use the --switch
the flag to use this document as the default document for the console session:
> doc new --switch
x5qffedimrovdpsr3andm3hdjo6g2nlaqstdm6oe3utblxsdh3eq
Active doc is now x5qffedi…
author:fhu3uk4w… doc:x5qffedi…
>
Next let's set a value in the document, and read it back.
author:fhu3uk4w… doc:x5qffedi…
> doc set foo bar
@fhu3uk4w…: foo = 6lujp3wx… (3 B)
author:fhu3uk4w… doc:x5qffedi…
> doc get foo -c
@fhu3uk4w…: foo = 6lujp3wx… (3 B)
bar
The -c
flag on the doc get
command tells iroh to fetch the actual contents.
Sync the document
Now let's actually sync this document with a second node. To disambiguate we'll call the node we've been working with so far "Node A", and the new one we'll create "Node B". We'll start by sharing write access to the document from Node A
:
Node A
author:fhu3uk4w… doc:x5qffedi…
> doc share write
lzkcgw25utyfj3o4q5dbeo5tyevcjutr25nagmzi5yfsgtqoeohqcig35slag7ibfh3ddcls4szbl3k4q6m6d7gnrpgnv66tlnk3gktxaabqa3bjffy7riydabwcsklryrlqbqfikyrmivybae
That long lzkcgw...
string is a ticket to join the document. Anyone who has that ticket can join & write to this document. Let's use it to join the document from Node B
, but first we need to create Node B. In another terminal, run:
$ export IROH_DATA_DIR=./
$ iroh start --rpc-port 1111
Listening addresses:
108.41.41.113:47896
108.41.41.113:62424
192.168.86.28:62424
DERP Region: 1
PeerID: msiymgtbgosahfrcftazqcbpz7n54z2kol2rd653fin6gh4remmq
Iroh has a default data directory, and a default port (1337
). We pass IROH_DATA_DIR=./
as an environment variable to override this directory, because we're already using it for our first iroh node. We also pass --rpc-port 1111
to override the default RPC port.
And now we'll create a fourth terminal to open a console for Node B
:
$ export IROH_DATA_DIR=./
$ iroh --rpc-port 1111 console
Welcome to the Iroh console!
Type `help` for a list of commands.
>
Now we can join the document from Node B
, pasting in the value of the ticket we created with doc share write
on Node A
:
Node B
> author new --switch
ksdx5fs4kwjmoaca2bod3z62vsm7ny42vubfxpczyr34trjvxp6q
Active author is now ksdx5fs4…
> doc join --switch lzkcgw25utyfj3o4q5dbeo5tyevcjutr25nagmzi5yfsgtqoeohqcig35slag7ibfh3ddcls4szbl3k4q6m6d7gnrpgnv66tlnk3gktxaabqa3bjffy7riydabwcsklryrlqbqfikyrmivybae
x5qffedimrovdpsr3andm3hdjo6g2nlaqstdm6oe3utblxsdh3eq
Active doc is now x5qffedi…
author:ksdx5fs4… doc:x5qffedi…
> doc get foo -c
@ksdx5fs4…: foo = 6lujp3wx… (3 B)
bar
The two consoles are now syncronized! We can see the value we set from Node A
on Node B
. Any edit you make in one console will be reflected in the other in real time.
To make this more interesting, try running this step on a separate computer. Iroh's networking stack will establish a connection for you. Nothing will change about these instructions.
Next Steps
Now that you've seen iroh in action, you're ready to start integrating it into your application. The Command Reference is a good place to start. It covers the CLI commands we used here, as well as code examples showing how to use Iroh in your language.