+++
title = "Operations"
template = "page_indiced.html"
slug = "/operations/"
+++

## Using Bridge {#using-bridge}

[Bridge](https://github.com/urbit/bridge) is the application we built for interacting with [Azimuth](https://azimuth.network), the Urbit PKI, and managing your Urbit ID. Importantly, Bridge also allows you to generate a keyfile that you will need to boot your ship so that it can use the Arvo network.

This guide assumes that you have an Urbit ID, or that you have found someone to send an Urbit ID to your Ethereum address and are looking to claim it.

### Online Bridge

To connect to Bridge, go to [https://bridge.urbit.org](https://bridge.urbit.org) into your browser, and enter your identity's credentials in the appropriate fields. If you were invited to claim an Urbit ID, it's very likely that you received an email that would direct you to Bridge, and you can simply follow the hyperlink in that email.

Once you arrive, proceed through the steps presented. You'll eventually arrive at a page with a few choices: `Invite`, `Admin`, and `Boot Arvo`. `Admin` is the only option that you're interested in right now; click on it. On the `Admin` page, click the `Download Arvo Keyfile` button. Once you have downloaded the keyfile, you can exit Bridge and proceed to [install the Urbit binary](@/install.md).

### Offline Bridge

Alternatively, Bridge can be run locally. It's more complicated, but we recommend this option for managing sufficiently valuable assets, such as several stars or more. To install local Bridge, navigate to the [release page on GitHub](https://github.com/urbit/bridge/releases/). Download the `.zip` file of the latest version. After you download it, follow the instructions below.

To use Bridge:

- Unzip the .zip file that you downloaded (bridge-$version.zip).
- Open up your command line interface (Terminal on OSX, Command Prompt on Windows).
- Navigate to the bridge-$version directory, where $version is the appropriate version number.
- Run this command: `python3 -m http.server 5000 --bind 127.0.0.1.`

You can then use the Bridge app by navigating to `http://localhost:5000` in your internet browser.

Note: Bridge allows you to both make reads and writes to the Ethereum blockchain. Writing to the blockchain, such as changing your networking keys, will incur a transaction cost that will require you to have some ETH in your address.

Once the program is running in your browser, go through the steps presented according to the type of wallet you have. You’ll be presented with a few login options. A notable option is Urbit Master Ticket. This is for those who used our Wallet Generator software. If you bought points from an Urbit sale and then used the Wallet Generator, your networking keys will be set for you. All other login options will require you to set your own networking keys.

### Accept your transfer

If you were given points by Tlon you likely already fully own them. But if someone else sent you a point, then you will first need to use Bridge to accept that transfer.

After you access your Ethereum address, if a point was sent to that address, you'll come to a page that has an `Incoming Transfers` header, under which is a graphic. Click the `Details ->` link under that graphic.

Now you'll be on the management page of your point. The transfer isn't completed yet, so click `Accept incoming transfer`. Then check both boxes and and click their associated `Sign Transaction` and `Send Transaction` buttons.

If you already own a point, click on the `Details ->` under your sigil in the `Your Points` section.

### Set your networking keys

If you just accepted a point, you'll be returned to your point screen. Notice that that links and buttons are now clickable. You now own this point!

Click the link that says `Set network keys`. The field presented in the resulting page expects a 32-byte hexadecimal string. If it's filled already, no action is required. If it is empty, you will need to generate such a string. You can generate this data any way you please, but in the terminal on MacOS or Linux, you can write

```sh
hexdump -n 32 -e '4/4 "%08X"' /dev/random
```

and use the result.

It should be noted that setting your network keys is an event on the Ethereum network and will therefore cost a trivial, but non-zero, amount of [gas](https://github.com/ethereum/wiki/wiki/Design-Rationale#gas-and-fees) to complete.

### Generate your keyfile

From the detail page associated with your point, click the `Generate Arvo Keyfile` link and you'll be taken to a page with a field titled `Network seed`. This field should already be filled in, and should match the hexadecimal string that you entered in the previous step. If it's not filled in or does not match, fill it in with the correct string.
Click `Generate ->`, which will download a keyfile onto your machine.

With that keyfile in hand, you can now exit Bridge and continue to the guide to [install the Urbit binary](@/install.md).

## Using your ship {#urbit-administration}

Your urbit (also called your _ship_) is a persistent Unix process that you mainly control from the console.

### Shutdown

You can turn your urbit off with `Ctrl-d` from the Chat or Dojo prompts.

You can force-quit your urbit with `Ctrl-z` from anywhere.

### Restart

To restart your urbit simply pass the name of your pier:

```sh
$ ./urbit some-planet
```

or

```sh
$ ./urbit comet
```

### Logging

To log an urbit's command line output to a file, use `script`:

```sh
$ script urbit.log ./urbit your-urbit
```

### Moving your pier

Piers are designed to be portable, but it _must_ be done while the urbit
is not running. Urbit networking is stateful, so you can't run two copies
of the same urbit in two places.

To move a pier, simply move the contents of the directory it lives in.
To keep these files as small as possible we usually use the `--sparse`
option in `tar`. With a pier `your-urbit/`, something like this should work:

```sh
tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/
scp your-old-server:~/your-urbit.tar.gz your-new-server:~
```

Then to unzip it, on your other Unix server, run:

```sh
tar xfvz your-urbit.tar.gz
```

Delete the tar file, and, after installing Urbit on your new server, start your urbit back up with:

```sh
./urbit your-urbit
```

### Console

Your Urbit terminal is separated into two parts: the prompt (the bottom line) and the record (everything above that). The record is shared; all the output from all the apps in your command set appears in it. The prompt is multiplexed.

In the CLI, Urbit apps can process your input before you hit return. To see this in action try entering `)` as the first character at the Dojo prompt. Since there is no Dojo command or Hoon expression that starts with ')', the Dojo rejects it.

`Ctrl-x` - Switches the prompt between running console apps

`Ctrl-c` - Crash current event.  Processed at the Unix layer and prints a stack
trace.

`Ctrl-d` - From Chat or Dojo, stops your Urbit process.

`Ctrl-z` - Stops the Urbit process from _anywhere_.

`↑` / `↓` - History navigation

The following emacs-style key bindings are available:

```
Ctrl-a    Cursor to beginning of the line (Home)
Ctrl-b    Cursor one character backward (left-arrow)
Ctrl-e    Cursor to the end of the line (End)
Ctrl-f     Cursor one character forward (right-arrow)
Ctrl-g    Beep; cancel reverse-search
Ctrl-k    Kill to end of line
Ctrl-l     Clear the screen
Ctrl-n    Next line in history (down-arrow)
Ctrl-p    Previous line in history (up-arrow)
Ctrl-r    Reverse-search
Ctrl-t    Transpose characters
Ctrl-u    Kill to beginning of line
Ctrl-y    Yank from kill buffer
```

### Landscape

On startup Urbit tries to bind to `localhost:80`. If you're already running something on port `80` -- such as any other HTTP server, or another urbit -- you'll find the urbit that you just started on `8080`, `8081`, and so on. For planets only, we also proxy web domains through Urbit's own servers. Any planet `~your-urbit` is also at `your-urbit.arvo.network`, but only after you [set up DNS](#dns-proxying).

Once running, you can sign into Landscape, your ship’s web interface, from `http://localhost` or `https://your-urbit.arvo.network`. Since our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS. You can find that on `8443`. Or `8444` (and so on) if you're already running something on `8443`.

### Moons {#moons}

Planets can spawn moons, which are meant for connected devices: phones, smart TVs, digital thermostats. The basic idea is that your planet runs permanently in a data center somewhere, while moons run on all your devices.  Each planet can issue ~4 billion (`2^32`) moons.

To generate a random moon from your planet, run:

```
~sampel-palnet:dojo> +moon
moon: ~faswep-navred-sampel-palnet
\/~.0wd.rZU67.3jSny.z1vda.7sr-s.EL1Jt.-76Nj.ugXxY.g6-Bx.HvKZl.G53oV.hPnXe.7U3E3.J4CEe.MEVuq.~08Nt\/
  .zNT0K.k-Ab~.Nn90d.OZ2fT.-XlQQ.Cfrkf.y6~K0.2Do09.EaE3W.BSK--.5Q~9N.y3QIP.eokH-.T6lwz.gg8MX.7LU5
  x.DJROE.IzQsy.OXOLr.IOE3a.-QI40.H5ukK.Cw-u4.uxE-y.V-o1F.Q84g0.effP0.de01g.600g1
\/                                                                                               \/
```

You must manually edit the output of `+moon` to get the correct format for the `<key>`:

- strip out the `\/`

- combine into one line, omitting spaces

- trim the leading `~.`

`<key>` would be `0wd.rZU67.3jSny.z1vda ... <snip> ... effP0.de01g.600g1`
in this example.

Put `<key>` in a file and that file becomes `<keyfile>`.

Another way of generating `<keyfile>` is:

```
~sampel-palnet:dojo> @moon/key +moon
moon: ~faswep-navred-sampel-palnet
```

`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key` and does not need editing to be used with the `-k` option.

You can use the resulting output in the same installation flow from the [Installing Urbit](@/install.md) guide, following the same scheme as for booting a planet. That scheme is:

```sh
$ ./urbit -w <moonname> -G <key> -c <piername>
```

or

```sh
$ ./urbit -w <moonname> -k <keyfile> -c <piername>
```

The `-c <piername>` argument is not required, but it is recommended; otherwise,
the resulting directory is a rather unwieldy moon name.

Here's how an example moon might be booted:

```sh
$ ./urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
```

or

```sh
$ ./urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
```

Moons are automatically synced to their parent `%kids` desk, and can control applications on their parent planet using `|link`.  

### Continuity breaches

While the Urbit network is in this alpha state, we sometimes have to reboot the whole network. This happens either when major changes need to be shipped or we hit a bug that can't be fixed over the air.

Because Urbit networking is stateful we call this a _continuity breach_. Everything has to be restarted from scratch. Your pier will continue to function after we have breached, but it won’t connect to the rest of the Urbit network.

When this happens, back up any files you'd like to save, shut down your urbit, and recreate it (as if you were starting for the first time).

## Creating a comet {#creating-a-comet}

**Comets** are urbits whose names are 128-bits or 16 syllables, such as:

`~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`

Comet names aren't quite as memorable as others, but they're disposable identities that anyone can make for free to join the live network.

### Booting a comet

To boot your comet, go into the command line and run the following command from the directory that was created during Urbit installation:

```sh
$ ./urbit -c mycomet
```

This will take a few minutes and will spin out a bunch of boot messages. Toward the end, you'll see something like:

```
ames: on localhost, UDP 31337.
http: live (insecure, public) on 8080
http: live ("secure", public) on 8443
http: live (insecure, loopback) on 12321
~dasres_marzod:dojo>
```

## DNS proxying {#dns-proxying}

We have a system that lets you request a domain name for your ship in the form of `ship.arvo.network`, where `ship` is your ship's name minus the `~`. This allows users to access their ships remotely using Landscape, our graphical web interface.

Stars and planets follow the same process DNS proxying process, and galaxies have their own requirements. Moons and comets are not supported.

### Planets and Stars

For a planet or star's DNS proxying request to be made and fulfilled, they must be hosting their ship someplace with a public IP address, and its HTTP server must be listening on port 80.

To get `ship.arvo.network` on a planet or star, you must set up DNS routing with its parent ship by starting the `:dns` app.

To do so, simply run this command in your ship's Dojo:

```
> :dns|request
```

You'll then be prompted to enter the public IP address of your ship. You can also pass the IP address as an argument, using the .0.0.0.0 (`@if`) syntax. For example:

```
> :dns|request .1.2.3.4
```

`:dns`, running locally, will make an HTTP request to that IP address on port 80 to confirm that it is itself available at that IP and port. If that fails, you'll receive a `%bail-early` message in `:chat-cli`; this request will retry a few times. If the self-check is successful, the request is relayed to `~zod`, and you'll receive a message saying, `request for DNS sent to ~zod`. Once `~zod` has acknowledged receipt of the request, your local `:dns` app will send a `:chat-cli` message saying `awaiting response from ~zod`.

The request will be picked up shortly, and the `ship.arvo.network` DNS record will be set to the given IP address. Once that's set up, `~zod` will be notified and `~zod` will, in turn, notify your ship. That ship will now try to verify that it can reach itself on `ship.arvo.network` over port 80. If it can't, it'll send a message saying, `unable to access via ship.arvo.network`. If it can, it will configure itself with that domain and say `confirmed access via ship.arvo.network`.

Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend Chrome or Brave.

### Galaxies

Galaxies are already required to have separate DNS entry at galaxy.urbit.org. There's no automated process for getting that binding, so if you're a galaxy-holder, get in touch with us at support@urbit.org.

There is a command for galaxies that will try to re-use their already-necessary Ames DNS entry for HTTPS:

```
> :dns|auto
```

This will make HTTP-requests to self-check availability over `galaxy.$AMES-DOMAIN` (currently galaxy.urbit.org), where `galaxy` is the galaxy's name minus the `~`.

Otherwise, `:dns|auto` works the same as `:dns|ip` does with stars and planets: if it's available or unavailable, Chat messages, and so on.

### More information

Configuring a ship's domain causes the `:acme` app to request an HTTPS certificate for that domain from LetsEncrypt. Note that LetsEncrypt also requires that the HTTP server be listening on port 80. If the certificate request fails, `:acme` will send a `:chat-cli` message with an explanation. Once the certificate is successfully retrieved, `:acme` will install it, causing the HTTP servers to restart. A secure server will be started on port 443 (the HTTPS default) if it's available. Otherwise, it will try 8443, and then increment to the next port until it can successfully bind one.

The built-in logic for listening on port 80 is similar. Urbit tries to bind port 80; if it cannot, it tries 8080, then increments until it can bind a port. Port 80 is available to unprivileged process on recent version of macOS. Otherwise, the process needs to either be run as root, or be given special permission (CAP\_NET_BIND on Linux).

## Messaging {#messaging}

Let’s get started using the `:chat-cli` application, also known more simply as _Chat_. It's the simplest way to talk to people using the command line interface.

### Quickstart

The most common uses of `:chat-cli` right now are communicating over a public chat channel on `~dopzod/urbit-help`, and sending direct messages. Everyone is more than welcome in `~dopzod/urbit-help`. It's the place to get help, ask questions and chat about Urbit in general.

There are two ways of using `:chat-cli`: from the terminal running the Urbit process, or through the Landscape web UI available from your ship’s URL address, mentioned earlier in this guide.

### Joining a chat

In `:chat-cli`, any kind of medium for a message is called a _chat_. There are four types of chats: the _channel_ (public with blacklist), _village_ (private with whitelist), the _journal_ (publicly readable, privately writable), and the _mailbox_ (privately readable, publicly writable). But for now we'll be dealing with the _channel_, a publicly accessible chatroom for general use. We'll discuss the other three kinds in the [manual](#messaging-manual) section later on.

Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from the Dojo prompt to the Chat prompt.

Then:

```
~your-urbit:chat-cli> ;join ~dopzod/urbit-help
```

Scrolling down your terminal window, you'll probably see a playback of previous `~dopzod/urbit-help` messages that you missed. You c

Post a line to `~dopzod/urbit-help:`

```
~your-urbit:chat-cli= Hello, world!
```

You'll see your message printed below messages from others that came before it. You can always type `;chats` in the `chat-cli` prompt to list all the chats you're in:



Glyphs will be automatically assigned to channels, but have the option of binding a glyph (single non-alphanumeric character) to the channel you're joining; the syntax is in the form of `;join ~dopzod/books +`. The chosen glyph will be the symbol that ends your prompt, and it will be what you use as a shortcut to switch to this channel.

```
~your-urbit:chat-cli= ;+
~your-urbit:chat-cli+
```

Use `;leave` to unsubscribe from a channel:

```
~your-urbit:chat-cli= ;leave ~dopzod/urbit-help
```

Now, let's create a channel we can invite some friends to:

```
~your-urbit:chat-cli= ;create channel /my-channel
```

Now you can tell your friends to `;join ~your-urbit/my-channel`.

### Direct messaging

To send a direct message to someone, first set your audience:

```
~your-urbit:chat-cli= ;~talsur-todres
```

You'll see your prompt change:

```
~your-urbit:chat-cli[~talsur-todres]
```

Now you and `~talsur-todres` can exchange messages directly.

```
~your-urbit:chat-cli[~talsur-todres] Hey buddy!
```

To set your audience back to `~dopzod/urbit-help`:

```
~your-urbit:chat-cli[~talsur-todres] ;~dopzod/urbit-help
```

You'll see your prompt change back:

```
~your-urbit:chat-cli=
```

#### Hoon

You can use Chat to evaluate Hoon code and share the results with everyone in a chat. To do so, preface your Hoon with `#`.

```
~your-urbit:chat-cli= #(add 2 2)
```

will print as

```
~your-urbit# (add 2 2)
4
```

### Creating and managing chats

As mentioned before, any urbit can host any number of chats. Existing chats can be deleted or modified with various commands. All commands in this section should be sent from the `chat-cli>` prompt.

#### Create

Syntax: `;create [type] /name +`, where `+` represents an optional glyph.

Creates and joins a chat, where `[type]` is any of the following:
- `channel`: public chat. Has a blacklist for write control.
- `village`: invite-only chat.
- `journal`: publicly readable, invite-only for writing.
- `mailbox`: publicly writeable, can only be read by its host.

Let's create an example mailbox:

```
sampel-palnet:chat-cli> ;create mailbox /coolbox ^
```

#### Delete

Syntax: `;delete /name`

Deletes a chat.

### Status

You'll see status notifications when people enter or leave chats you're subscribed to.

#### Notifications off

Syntax: `;set quiet`

Turn off status (and config) notifications.

#### Notifications on

Syntax: `;unset quiet`

Turn on status (and config) notifications.

#### Chat glyphs

Glyphs are found at the end of your prompt to as a quick indicator of where
your messages will be sent.

Glyphs are assigned by chat hash out of the following list:

```
> = + - } ) , . " ' ^ $ % & @
```

Alphanumeric characters and `|#;:*~_` are reserved; all others (the
above list, and `\/!?({<`) can be manually assigned.

For example, `-` the glyph at the end of the prompt below might indicates that
messages sent from this prompt will go to some chat with that glyph:

```
~sampel-palnet:chat-cli-
```

To see what chat is bound to a glyph, use the `;what` command followed by the
glyph in question, or use `;what` without specifying a glyph to see all of your
subscriptions which are bound to glyphs. For example, to see `=`:

```
~sampel-palnet:chat-cli> ;what =
~dopzod/urbit-help
```

To see all of your glyph-bound subscriptions:

```
~sampel-palnet:chat-cli> ;what
> ~paldev/numismatic-forum
. ~middev/ny-martians
= ~dopzod/urbit-help
```

Not every audience has a glyph, however. When the audience doesn't have a glyph,
such as in the case of direct-messaging a ship, we see their name at the end of
the prompt instead. Here we're talking directly to `~dannum-mitryl`:

```
~sampel-palnet:chat-cli[~dannum-mitryl]
```

#### Bind

Syntax: `;bind [glyph] /chat-name`

Assigns the chosen glyph to a chat owned by your ship.

For example:

```
~sampel-palnet:chat-cli> ;bind + /my-chat
```

#### Unbind

Syntax: `;unbind [glyph] /chat-name`

Unassigns the chosen glyph from a chat owned by your ship.

For example:

```
~sampel-palnet:chat-cli> ;unbind + /my-chat
```

#### Prefixes

Received posts are prefixed with a glyph to let you know what the
audience is. You can activate an individual post to see the full
audience.

There are a few special-purpose glyphs:

- `|` - Informational messages
- `:` - Posts directly to you
- `;` - Posts to you and others (a multiparty conversation)
- `*` - Posts to a complex audience that doesn't directly include you.


### Configuration

#### Set audience

`;~ship/chat`

Set audience to `~ship/chat`.

#### Set audience by glyph

Syntax: `;[glyph]`

Set audience to the chat previously bound to the chosen glyph.

#### Set audience to ship

syntax `;~ship`

Set audience to another ship.

#### Set audience to own chat

Syntax: `;%chat`

Set audience to a chat on your own ship.

#### Set audience and send message

Syntax: `;~dannum-mitryl this is a private message`

Set the audience and send a post in the same line. This works for all of the
above audience commands.

Your audience is configured with regard to the following rules (in order):

- if you manually set the audience, that audience.
- if you activated a post, the post you activated.
- audience of the last post sent.

### Miscellaneous configuration

#### Show timestamps

Syntax: `;set showtime`

Show the timestamp for each message. This is set by default.

#### Hide timestamps

Syntax: `;unset showtime`

Stop showing the timestamp for each message.

#### Change timezone

Syntax: `;set timezone [+/-][hours]`

Adjust the display of timestamps to a specific timezone. Relative to UTC.

#### Sound notification on

Syntax: `;set notify`

Emit a terminal bell sound if your six-syllable ship name is mentioned in
a message. This is set by default.

#### Sound notification off

Syntax `;unset notify`

Do not notify when your ship name is mentioned.

#### Set width

Syntax: `;set width [number]`

Set the rendering width of `:chat-cli` to a specific number of characters.
(Minimum of 30.)


## Shell {#using-the-shell}

The Dojo is our shell; it processes system commands and returns output. It's a
good place to quickly experiment with Urbit. On the surface the Dojo is just a
Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
data in Urbit.

### Quickstart

You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
commands.

#### Math

Evaluate a Hoon expression (whitespace matters):

```
~your-urbit:dojo> (add 2 2)
~your-urbit:dojo> %+  add  2  2
```

Tall-form Hoon may require multiple lines:

```
~your-urbit:dojo> %+  add
~your-urbit:dojo< 2
~your-urbit:dojo< 2
```

Hoon uses something called [the subject](@/docs/hoon/hoon-tutorial/the-subject-and-its-legs.md).
The Dojo has its own subject and that's where Hoon's equivalent of variables,
called faces, are stored.

Use `=var` to save faces to the Dojo subject.

```
~your-urbit:dojo> =foo (add 2 2)
```

Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
face in a `.hoon` file in this way.

#### System commands

Use `=dir` to set the current working directory:

```
~your-urbit:dojo> =dir %/gen
```

(`%` represents your current directory. For a complete explanation on urbit
paths, see the [filesystem section](#filesystem).)

Generators (files in `/gen`) are run with `+`:

```
~your-urbit:dojo> +hello 'world'
```

Save output to a file in `%clay` with `*`:

```
~your-urbit:dojo> *some/file/path/hoon 'hello world'
```

Run system commands from `:hood`, like `reload`, using `|`:

```
~your-urbit:dojo> |reload %eyre
```

### Generators

Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`
directory. Many Dojo commands exist in the form of generators. The syntax for
running a generator is `+genname` for a generator saved as `genname.hoon`.

#### `+cat`

Accepts a path and displays the file. Similar to Unix `cat`.

```
~your-urbit:dojo> +cat %/gen/curl/hoon
```

#### `+code`

Generates a code that is used to remotely log into your ship. No
arguments.

```
~your-urbit:dojo> +code
```

#### `+curl`

Retrieves data from a URL. Accepts a `tape`. Similar to Unix `curl`.

```
~your-urbit:dojo> +curl "http://nyt.com"
```

#### `+hello`

Just prints the argument. Accepts a `@ta`.

```
~your-urbit:dojo> +hello 'mars'
```

#### `+ls`

Similar to Unix `ls`. Accepts a path.

```
~your-urbit:dojo> +ls %/gen
~your-urbit:dojo> +ls /~talsur-todres/home/2/gen/program
```

#### `+moon`

Generates a random moon from a planet. No arguments.

```
~your-urbit:dojo> +moon
```

#### `+solid`

Compile the current state of the kernel and output a
noun. Usually downloaded to a file in unix. No arguments.

```
~your-urbit:dojo> .urbit/pill +solid
```

#### `+test`

Testrunner. Can test multiple generators at once, conventionally ones
in the `/test` folder. Takes a path.

```
~your-urbit:dojo> +test /lib
```

#### `+ticket`

Generate a ticket for an urbit ship. Takes an urbit name (`@p`).


```
~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
```

#### `+tree`

Generate a recursive directory listing. Takes a path.

```
~your-urbit:dojo> +tree %/sys
```

### Hood

The hood is the system daemon. See `gen/hood` and `app/hood`.

`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts
an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).

```
~your-urbit:dojo> |hi ~binzod "you there?"
```

`|link` / `|unlink` - Link / unlink a remote app. Accepts an
Urbit name and an app name.

```
~your-urbit:dojo> |link ~talsur-todres %octo
```

`|mass` - Prints the current memory usage of all the kernel modules.
No arguments.

```
~your-urbit:dojo> |mass
```

`|reload` - Reloads a kernel module (vane) from source. Accepts any
number of vane names.

```
~your-urbit:dojo> |reload %clay %eyre
```

`|reset` - Reloads `hoon.hoon` and all modules. No arguments.

```
~your-urbit:dojo> |reset
```

`|start` - Starts an app. Accepts an app name.

```
~your-urbit:dojo> |start %curl
```

---

### Dojo manual

#### Sources and sinks

A Dojo command is either a **source** or a **sink**. A source is just something
that can be printed to your console or the result of some computation. A
sink is an **effect**: a change to the filesystem, a network message, a
change to your environment, or a typed message to an app.

Sources can be chained together, but we can only produce one effect per
command.

#### Sinks

#### `=` - Set variable

Set any environment variable:

```
~your-urbit:dojo> =foo 42
~your-urbit:dojo> (add 2 foo)

44
```

Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
variable in a `.hoon` file in this way.

#### Special variables

There are a few special variables that the Dojo maintains.

#### `:` - Send to app

`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.

Send a `helm-hi` message to `hood`:

```
~your-urbit:dojo> :hood &helm-hi 'hi'
```

Apps usually expect marked data, so `&` is often used here.

#### `*` - Save in `%clay`

Save a new `.hoon` file in `gen`:

```
~your-urbit:dojo> *%/gen/foo/hoon '# hello'
```

The last component of the path is expected to be the mark (or mime
type).

#### `.` - Export to Unix

Export a noun to Unix with `.`:

```
~your-urbit:dojo> .foo/bar/baz (add 2 2)
```

Which creates a file at `pier/.urb/put/foo/bar.baz`.

This is very often used with `+solid`:

```
~your-urbit:dojo> .urbit/pill +solid
```

Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`

### Sources

#### `&` - Mark conversion

Convert between marks using `&`, with the destination mark first. You can stack multiple mark conversions together, and some marks can only be converted to specific other marks. In this example, [Udon](@/docs/arvo/sail-and-udon.md#udon) is converted to `&hymn` (a mark which supplies the `html`, `head`, `body`, and closing tags) first, before being converted to HTML:

```
~your-urbit:dojo>&html &hymn &udon ';h1#hello: hello'
'<html><head></head><body><h1 id="hello">hello</h1></body></html>'
```

Performing a conversion straight from Udon to the `&hymn` mark reveals a bit more about its mark conversion:

```
~your-urbit:dojo>&hymn &udon ';h1#hello: hello'
[[%html ~] [[%head ~] ~] [[%body ~] [g=[n=%h1 a=~[[n=%id v="hello"]]] c=~[[g=[n=%$ a=~[[n=%$ v="hello"]]] c=~]]] ~] ~]
```

As does converting straight from Udon to HTML:

```
~your-urbit:dojo>&html &udon ';h1#hello: hello'
';h1#hello: hello'
```

#### `_` - Run a function

Use `_` to run a gate (or function):

Write an arbitrary function and pass data to it:

```
~your-urbit:dojo> _|=([a=@] (mul a 3)) 3
9
```

Use a function to get the status code from an http request:

```
~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
301
```

#### `+` `-` - HTTP requests

`+http[s]://example.com` - sends a GET request

`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
JSON `"hi"` in the body.

`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
JSON `"hi"` in the body.

Note that the first of these is a source while the last two are sinks.

#### `+` - Generators

Generators are simple Hoon scripts loaded from the filesystem. They live
in `gen/`.

An example of a generator that is built into your urbit is `+code`. It produces
the code needed to log into your ship remotely.

```
~your-urbit:dojo> +code
fintyr-haldet-fassev-solhex
```

### Variables

You can use `=` to set an environment variable in Dojo, but there are
a few reserved names that have special uses.

#### `dir`

Current working `%clay` desk and revision. Read / write.

**Examples:**

```
~your-urbit:dojo> =dir %/gen
~your-urbit:dojo> +ls %
404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
```

#### `lib`

Current set of libraries (`/lib`) in your environment. Can be set
with `/+`. Read / write.

**Examples:**

```
~your-urbit:dojo> /+  number-to-words
```
Now we can use arms from lib/number-to-words.hoon
```
~your-urbit:dojo> (to-words:eng-us:number-to-words 123.456)
```

#### `sur`

Current set of structures (`/sur`) in your environment. Can be set
with `/-`. Read / write.

**Examples:**

```
~your-urbit:dojo> /-  sole
```
Now we can use arms in sur/sole.hoon.
```
~your-urbit:dojo> `sole-effect:sole`[%bel ~]
```

#### `now`

The current (128-bit `@da`) time. Read-only.

**Example:**

```
~your-urbit:dojo> now
~2016.3.21..21.10.57..429a
```

#### `our`

The current urbit ship. Read-only.

**Example:**

```
~your-urbit:dojo> our
~your-urbit
```

#### `eny`

512 bits of entropy. Read-only.

**Example:**

```
~your-urbit:dojo> eny
\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/
  8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn
\/
```

### Troubleshooting

If you encounter `%dy-edit-busy` while entering commands, it is
because your Dojo is blocked on a timer or an HTTP request. Type backspace
and your Dojo will end the blocked command.


## Filesystem {#filesystem}

Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global,
referentially transparent namespace. An easy way to think about it is like typed
`git`.

The most common way to use Clay is to mount a Clay node in a Unix directory. The mounted directory is always at the root of your pier directory.

### Quickstart

This quick-start guide will walk you through some common commands. Follow along
using your Dojo. When you get a `>=` message after entering a command, this means
that the command was successful.

It's important to note that whenever you want to sync changes from your Unix
directory to your ship, you must use the `|commit %desk` command, where `%desk`
is the desk that you'd like to sync to.

When developing it's a good idea to use a separate desk. Create a `%sandbox`
desk based on the `%home` desk:

```
~your-urbit:dojo> |merge %sandbox ~your-urbit %home
```

Running `our` produces your ship-name, meaning that you can run the following
command instead of typing out the entire thing. Useful for comets due to their
very long names.

```
~your-urbit:dojo> |merge %sandbox our %home
```

Most of the time we want to use Clay from Unix.  Mount the entire contents of
your `sandbox` desk to Unix:

```
~your-urbit:dojo> |mount /=sandbox=
```

To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`
displays files in the current directory, and `+cat` displays the contents of
a file.

We can use `%` to mean "current directory." The result of the command below
is just like using `ls` in a Unix terminal.

```
~your-urbit:dojo> +ls %
```

Notice how `+cat %` does the same thing. That's because everything in Clay,
including directories, is a file.

Sync from your friend `~some-ship`'s `%experiment` desk to your
`%sandbox` desk:

```
~your-urbit:dojo> |sync %sandbox ~some-ship %experiment
```

If and when your sync is successful, you will receive a message:

```
activated sync from %experiment on ~some-ship to %sandbox
```

The ship that you sync from will get their own message indicating that you're
both connected as peers:

```
; ~your-urbit is your neighbor.
```

---

### Clay manual

#### Paths

A path in Clay is a list of URL-safe text, restricted to the characters
`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
In other words, paths are expressed as `/foo/bar/baz`. File extensions are
separated from file names with `/`, not `.`. Extensions are syntactically
identical to subdirectories, except that they must terminate the path.

Paths begin with a piece of data called a `beak`. A beak is formally a
`(p=ship q=desk r=case)`; it has three components, and might look like
`/~dozbud-namsep/home/11`.

The first `beak` component is `ship`, which is, as you might guess, the name of
an Urbit ship. The second component is `desk`, which is a workspace meant to
contain other directories; the default desk is `%home`. The third component is
`case`, which represents version information in various ways: date and time;
a version sequence, which is a value incremented by one whenever a file on the
given `desk` is modified; or an arbitrary plaintext label.

You can find what your `beak` is at any given moment by
typing `%` in the Dojo and looking at the first three results.

We use `beak`s because, unlike the current internet, the Urbit network uses a
global namespace. That means that a file named `example.hoon` in the `/gen`
directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
universal address to anyone else on the network:
`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of
course, doesn't mean that everyone on the network has privileges to access that
path.

The structure that combines a `beak` with further path information is called a
`beam`.

#### Relative paths

The `%` command, which we gestured at in the above section, represents the
**relative path**, which is the path where you are currently working. If your
working directory is just your home desk, indicated by the
prompt `~your-planet:dojo>`, then running the command below will print your
working directory's `beam` information: your `beak`, and a `~` that represents
the empty list since no path is present.

```
~your-urbit:dojo> %
```

`%`s can be stacked to indicate one level further up in the hierarchy for each
additional `%`. Try the following command:

```
~your-planet:dojo> %%%
```

You'll probably notice that it only has your ship name and the empty list. The
two additional `%`s abandoned the `case` and the `desk` information by moving
up twice the hierarchy.

There are no local relative paths. `/foo/bar` must be written as
`%/foo/bar`.

#### Substitution

You don't need to write out the explicit path every time you want to reference
somewhere outside of your working directory. You can substitute `=` for the
segments of a path.

Recall that a full address in the the Urbit namespace is a `beam`: the
`/ship/desk/case/path`. If you've switched to another desk before, you're
already familiar with substitution syntax:

```
~your-urbit:dojo> =dir /=sandbox=
```

The above command substitutes uses substitution to use your current `ship` and
`case`; only the `desk` argument, which is located between the other two, is
given something new. Without substitution, you would need to write:

```
~your-urbit:dojo> =dir /~your-urbit/home/85
```

Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
paths. For example, if you are in the `/gen` directory, you can reference a file
in the `/app` directory like below. (`+cat` displays the contents of a file).

```
~your-urbit:dojo> =dir %/gen
~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> +cat /===/app/curl/hoon
```

Note what was substituted out, and note that we don't need to separate `=` with
`/`.

If we changed our working directory to something called `/gen/gmail`, we could
access a file called

```
~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %/gmail
~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /===/app/=/split/hoon
```

Because both paths share a directory named `/gmail` at the same position in the
address hierarchy – which, if you recall, is just a `list` – the above command
works!

We can do the same thing between desks. If `%sandbox` has been merged with
`%home`, the following command will produce the same results as the above
command.

```
~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /=sandbox=/app/=/split/hoon
```

Most commonly this is used to avoid having to know the current revision
number in the `dojo`: `/~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example/hoon`

#### Changing directories

Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.

For example, the syntax to navigate to `/home/gen/ask` is:

```
~your-urbit:dojo> =dir /=home=/gen/ask
```

This command will turn your prompt into something like this:

```
~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask>
```

Using `=dir` without anything else uses the null path, which returns you to
your home desk.

```
~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask> =dir
```

Your dojo prompt will turn back into `~your-urbit:dojo>`.

To go up levels in the path hierarchy, recall the relative path expression
`%`. Stacking them represents another level higher in the hierarchy than
the current working directory for each `%` beyond the initial. The command below
brings you one level up:

```
~your-urbit:dojo> =dir %/gen
~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %%
```

### Revision-control

#### Mount

Syntax: `|mount /clay/path [Unix-name]`

Mount the `clay-path` at the Unix mount point `Unix-name`.

**Examples:**

```
|mount %/gen generators
```

Mounts `%/gen` to `/generators` inside your pier directory.

#### Unmount

```
|unmount [clay-path || Unix-name]
```

Unmount the path or name from Unix.

**Examples:**

```
|unmount %/gen
```

Unmounts the Clay path `%/gen` from whatever name it was mounted as.

```
|unmount %generators
```

Unmounts the Unix path `/generators`.

#### Merge

```
|merge desk beak[, =gem strategy]
```

Merges a `beak` into a `desk` using an optional merge `strategy`.

A `beak` is a ship-desk-case triple, encoded as a
path(`/~dozbud/home/2`)

**Examples:**

```
|merge %home-work /=home=, =gem %fine
```

Merge `/=home=` into `%home-work` using merge strategy `%fine`.

```
|merge %examples ~wacbex-ribmex %examples
```

Merge the `%examples` desk from `~waxbex-ribmex`

#### Sync

```
|sync desk plot [plot-desk]
```

Subscribe to continuous updates from remote `plot` on local `desk`.
`plot-desk` can specify the remote `desk` name. When omitted it defaults
to being the same as `desk`. Non-comet urbits have
`|sync %home ~parent %kids` automatically set up (where `~parent` is the
planet that issued a moon, the star that issued a planet, or the galaxy
that issued a star).

**Examples:**

```
|sync %home-local ~dozbud %home

|sync %home ~doznec
```

#### Unsync

```
|unsync desk plot [plot-desk]
```

Unsubscribe from updates from remote `plot` on local `desk` with
optional `plot-desk`. Arguments must match original `|sync` command.

Example:

```
|unsync %home-local ~dozbud %home
```

#### Label

```
|label desk name`
```

Label the current version of `desk` `name`.

Example:

```
|label %home release
```

### Merge strategies

`%init` - used if it's the first commit to a desk. Also can be used to
"reinitialize" a desk – revision numbers keep going up, but the new
revision isn't necessarily a descendent of the previously numbered
version, allowing merges to be rerun.

`%this` - keep what's in Bob's desk, but join the ancestry.

`%that` - take what's in Alice's desk, but join the ancestry. This is
the reverse of `%this`. This is different from `%init` because the new
commit has both sides in its ancestry.

`%fine` - "fast-forward" merge. This succeeds if and only if one head is in the
ancestry of the other.

`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
use as our merge base.

A `%meet` merge only succeeds if the changes from the merge base to
Alice's head (hereafter, "Alice's changes") are in different files than
Bob's changes. In this case, the parents are both Alice's and Bob's
heads, and the data is the merge base plus Alice's changed files plus
Bob's changed files.

A `%mate` merge attempts to merge changes to the same file when both
Alice and Bob change it. If the merge is clean, we use it; otherwise, we
fail. A merge between different types of changes – for example,
deleting a file vs changing it – is always a conflict. If we succeed,
the parents are both Alice's and Bob's heads, and the data is the merge
base plus Alice's changed files plus Bob's changed files plus the merged
files.

A `%meld` merge will succeed even if there are conflicts. If there are
conflicts in a file, then we use the merge base's version of that file,
and we produce a set of files with conflicts. The parents are both
Alice's and Bob's heads, and the data is the merge base plus Alice's
changed files plus Bob's changed files plus the successfully merged
files plus the merge base's version of the conflicting files.

`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
doesn't we use an `%init` merge. Otherwise, we progressively try
`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
the scratch desk with the `%meld` option to force the merge. Finally, we
annotate any conflicts, if we know how.

### Manipulation

#### `+cat`

Syntax: `+cat path [path ...]`

Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
contents. If that `path` is a file, the contents of the file is printed. If the
`path` terminates in a directory, the list of names at that path is produced.

#### `+ls`

Syntax: `+ls path`

Similar to Unix `ls`. `+ls` takes a single `path`.

Produces a list of names at the `path`.

```
~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
```

#### `|rm`

Syntax: `|rm path`

Remove the data at `path`. `Path` must be a path to the actual node, not a
'directory'.

#### `|cp`

Syntax: `|cp to from`

Copy the file at `from` into the path `to`.

#### `|mv`

Syntax: `|mv to from`

Move the file at `from` into the path `to`.

In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
doesn't happen unless the `|cp` succeeds.