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.

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:

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:

> 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.

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.