content/operations.md · urbit.org

git.iko.soy/urbit.org

on f33f00a help sign in

urbit.org/content/operations.md

1497 lines 45 kB history raw

1+++

2title = "Operations"

3template = "page_indiced.html"

4slug = "/operations/"

5+++

7## Using Bridge {#using-bridge}

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

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

13### Online Bridge

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

17Once 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).

19### Offline Bridge

21Alternatively, 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.

23To use Bridge:

25- Unzip the .zip file that you downloaded (bridge-$version.zip).

26- Open up your command line interface (Terminal on OSX, Command Prompt on Windows).

27- Navigate to the bridge-$version directory, where $version is the appropriate version number.

28- Run this command: `python3 -m http.server 5000 --bind 127.0.0.1.`

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

32Note: 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.

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

36### Accept your transfer

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

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

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

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

46### Set your networking keys

48If 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!

50Click 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

52```sh

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

54```

56and use the result.

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

60### Generate your keyfile

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

63Click `Generate ->`, which will download a keyfile onto your machine.

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

67## Using your ship {#urbit-administration}

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

71### Shutdown

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

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

77### Restart

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

81```sh

82$ ./urbit some-planet

83```

85or

87```sh

88$ ./urbit comet

89```

91### Logging

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

95```sh

96$ script urbit.log ./urbit your-urbit

97```

99### Moving your pier

100

101Piers are designed to be portable, but it _must_ be done while the urbit

102is not running. Urbit networking is stateful, so you can't run two copies

103of the same urbit in two places.

104

105To move a pier, simply move the contents of the directory it lives in.

106To keep these files as small as possible we usually use the `--sparse`

107option in `tar`. With a pier `your-urbit/`, something like this should work:

108

109```sh

110tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/

111scp your-old-server:~/your-urbit.tar.gz your-new-server:~

112```

113

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

115

116```sh

117tar xfvz your-urbit.tar.gz

118```

119

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

121

122```sh

123./urbit your-urbit

124```

125

126### Console

127

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

129

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

131

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

133

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

135trace.

136

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

138

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

140

141`↑` / `↓` - History navigation

142

143The following emacs-style key bindings are available:

144

145```

146Ctrl-a Cursor to beginning of the line (Home)

147Ctrl-b Cursor one character backward (left-arrow)

148Ctrl-e Cursor to the end of the line (End)

149Ctrl-f Cursor one character forward (right-arrow)

150Ctrl-g Beep; cancel reverse-search

151Ctrl-k Kill to end of line

152Ctrl-l Clear the screen

153Ctrl-n Next line in history (down-arrow)

154Ctrl-p Previous line in history (up-arrow)

155Ctrl-r Reverse-search

156Ctrl-t Transpose characters

157Ctrl-u Kill to beginning of line

158Ctrl-y Yank from kill buffer

159```

160

161### Landscape

162

163On 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).

164

165Once 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`.

166

167### Moons {#moons}

168

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

170

171To generate a random moon from your planet, run:

172

173```

174~sampel-palnet:dojo> +moon

175moon: ~faswep-navred-sampel-palnet

176\/~.0wd.rZU67.3jSny.z1vda.7sr-s.EL1Jt.-76Nj.ugXxY.g6-Bx.HvKZl.G53oV.hPnXe.7U3E3.J4CEe.MEVuq.~08Nt\/

177 .zNT0K.k-Ab~.Nn90d.OZ2fT.-XlQQ.Cfrkf.y6~K0.2Do09.EaE3W.BSK--.5Q~9N.y3QIP.eokH-.T6lwz.gg8MX.7LU5

178 x.DJROE.IzQsy.OXOLr.IOE3a.-QI40.H5ukK.Cw-u4.uxE-y.V-o1F.Q84g0.effP0.de01g.600g1

179\/ \/

180```

181

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

183

184- strip out the `\/`

185

186- combine into one line, omitting spaces

187

188- trim the leading `~.`

189

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

191in this example.

192

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

194

195Another way of generating `<keyfile>` is:

196

197```

198~sampel-palnet:dojo> @moon/key +moon

199moon: ~faswep-navred-sampel-palnet

200```

201

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

203

204You 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:

205

206```sh

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

208```

209

210or

211

212```sh

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

214```

215

216The `-c <piername>` argument is not required, but it is recommended; otherwise,

217the resulting directory is a rather unwieldy moon name.

218

219Here's how an example moon might be booted:

220

221```sh

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

223```

224

225or

226

227```sh

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

229```

230

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

232

233### Continuity breaches

234

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

236

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

238

239When 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).

240

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

242

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

244

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

246

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

248

249### Booting a comet

250

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

252

253```sh

254$ ./urbit -c mycomet

255```

256

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

258

259```

260ames: on localhost, UDP 31337.

261http: live (insecure, public) on 8080

262http: live ("secure", public) on 8443

263http: live (insecure, loopback) on 12321

264~dasres_marzod:dojo>

265```

266

267## DNS proxying {#dns-proxying}

268

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

270

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

272

273### Planets and Stars

274

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

276

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

278

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

280

281```

282> :dns|request

283```

284

285You'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:

286

287```

288> :dns|request .1.2.3.4

289```

290

291`: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`.

292

293The 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`.

294

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

296

297### Galaxies

298

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

300

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

302

303```

304> :dns|auto

305```

306

307This 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 `~`.

308

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

310

311### More information

312

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

314

315The 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).

316

317## Messaging {#messaging}

318

319Let’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.

320

321### Quickstart

322

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

324

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

326

327### Joining a chat

328

329In `: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.

330

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

332

333Then:

334

335```

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

337```

338

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

340

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

342

343```

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

345```

346

347You'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:

348

349

350

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

352

353```

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

355~your-urbit:chat-cli+

356```

357

358Use `;leave` to unsubscribe from a channel:

359

360```

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

362```

363

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

365

366```

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

368```

369

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

371

372### Direct messaging

373

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

375

376```

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

378```

379

380You'll see your prompt change:

381

382```

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

384```

385

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

387

388```

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

390```

391

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

393

394```

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

396```

397

398You'll see your prompt change back:

399

400```

401~your-urbit:chat-cli=

402```

403

404#### Hoon

405

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

407

408```

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

410```

411

412will print as

413

414```

415~your-urbit# (add 2 2)

4164

417```

418

419### Creating and managing chats

420

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

422

423#### Create

424

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

426

427Creates and joins a chat, where `[type]` is any of the following:

428- `channel`: public chat. Has a blacklist for write control.

429- `village`: invite-only chat.

430- `journal`: publicly readable, invite-only for writing.

431- `mailbox`: publicly writeable, can only be read by its host.

432

433Let's create an example mailbox:

434

435```

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

437```

438

439#### Delete

440

441Syntax: `;delete /name`

442

443Deletes a chat.

444

445### Status

446

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

448

449#### Notifications off

450

451Syntax: `;set quiet`

452

453Turn off status (and config) notifications.

454

455#### Notifications on

456

457Syntax: `;unset quiet`

458

459Turn on status (and config) notifications.

460

461#### Chat glyphs

462

463Glyphs are found at the end of your prompt to as a quick indicator of where

464your messages will be sent.

465

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

467

468```

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

470```

471

472Alphanumeric characters and `|#;:*~_` are reserved; all others (the

473above list, and `\/!?({<`) can be manually assigned.

474

475For example, `-` the glyph at the end of the prompt below might indicates that

476messages sent from this prompt will go to some chat with that glyph:

477

478```

479~sampel-palnet:chat-cli-

480```

481

482To see what chat is bound to a glyph, use the `;what` command followed by the

483glyph in question, or use `;what` without specifying a glyph to see all of your

484subscriptions which are bound to glyphs. For example, to see `=`:

485

486```

487~sampel-palnet:chat-cli> ;what =

488~dopzod/urbit-help

489```

490

491To see all of your glyph-bound subscriptions:

492

493```

494~sampel-palnet:chat-cli> ;what

495> ~paldev/numismatic-forum

496. ~middev/ny-martians

497= ~dopzod/urbit-help

498```

499

500Not every audience has a glyph, however. When the audience doesn't have a glyph,

501such as in the case of direct-messaging a ship, we see their name at the end of

502the prompt instead. Here we're talking directly to `~dannum-mitryl`:

503

504```

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

506```

507

508#### Bind

509

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

511

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

513

514For example:

515

516```

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

518```

519

520#### Unbind

521

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

523

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

525

526For example:

527

528```

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

530```

531

532#### Prefixes

533

534Received posts are prefixed with a glyph to let you know what the

535audience is. You can activate an individual post to see the full

536audience.

537

538There are a few special-purpose glyphs:

539

540- `|` - Informational messages

541- `:` - Posts directly to you

542- `;` - Posts to you and others (a multiparty conversation)

543- `*` - Posts to a complex audience that doesn't directly include you.

546### Configuration

548#### Set audience

550`;~ship/chat`

552Set audience to `~ship/chat`.

553

554#### Set audience by glyph

555

556Syntax: `;[glyph]`

557

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

559

560#### Set audience to ship

561

562syntax `;~ship`

563

564Set audience to another ship.

565

566#### Set audience to own chat

567

568Syntax: `;%chat`

569

570Set audience to a chat on your own ship.

571

572#### Set audience and send message

573

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

575

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

577above audience commands.

578

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

580

581- if you manually set the audience, that audience.

582- if you activated a post, the post you activated.

583- audience of the last post sent.

584

585### Miscellaneous configuration

586

587#### Show timestamps

588

589Syntax: `;set showtime`

590

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

592

593#### Hide timestamps

594

595Syntax: `;unset showtime`

596

597Stop showing the timestamp for each message.

598

599#### Change timezone

600

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

602

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

604

605#### Sound notification on

606

607Syntax: `;set notify`

608

609Emit a terminal bell sound if your six-syllable ship name is mentioned in

610a message. This is set by default.

611

612#### Sound notification off

613

614Syntax `;unset notify`

615

616Do not notify when your ship name is mentioned.

617

618#### Set width

619

620Syntax: `;set width [number]`

621

622Set the rendering width of `:chat-cli` to a specific number of characters.

623(Minimum of 30.)

624

625

626## Shell {#using-the-shell}

627

628The Dojo is our shell; it processes system commands and returns output. It's a

629good place to quickly experiment with Urbit. On the surface the Dojo is just a

630Hoon REPL. On the inside, the Dojo is a system for operating on and transforming

631data in Urbit.

632

633### Quickstart

634

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

636commands.

637

638#### Math

639

640Evaluate a Hoon expression (whitespace matters):

641

642```

643~your-urbit:dojo> (add 2 2)

644~your-urbit:dojo> %+ add 2 2

645```

646

647Tall-form Hoon may require multiple lines:

648

649```

650~your-urbit:dojo> %+ add

651~your-urbit:dojo< 2

652~your-urbit:dojo< 2

653```

654

655Hoon uses something called [the subject](@/docs/hoon/hoon-tutorial/the-subject-and-its-legs.md).

656The Dojo has its own subject and that's where Hoon's equivalent of variables,

657called faces, are stored.

658

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

660

661```

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

663```

664

665Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

666face in a `.hoon` file in this way.

667

668#### System commands

669

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

671

672```

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

674```

675

676(`%` represents your current directory. For a complete explanation on urbit

677paths, see the [filesystem section](#filesystem).)

678

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

680

681```

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

683```

684

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

686

687```

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

689```

690

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

692

693```

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

695```

696

697### Generators

698

699Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`

700directory. Many Dojo commands exist in the form of generators. The syntax for

701running a generator is `+genname` for a generator saved as `genname.hoon`.

702

703#### `+cat`

704

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

706

707```

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

709```

710

711#### `+code`

712

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

714arguments.

715

716```

717~your-urbit:dojo> +code

718```

719

720#### `+curl`

721

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

723

724```

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

726```

727

728#### `+hello`

729

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

731

732```

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

734```

735

736#### `+ls`

737

738Similar to Unix `ls`. Accepts a path.

739

740```

741~your-urbit:dojo> +ls %/gen

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

743```

744

745#### `+moon`

746

747Generates a random moon from a planet. No arguments.

748

749```

750~your-urbit:dojo> +moon

751```

752

753#### `+solid`

754

755Compile the current state of the kernel and output a

756noun. Usually downloaded to a file in unix. No arguments.

757

758```

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

760```

761

762#### `+test`

763

764Testrunner. Can test multiple generators at once, conventionally ones

765in the `/test` folder. Takes a path.

766

767```

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

769```

770

771#### `+ticket`

772

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

774

775

776```

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

778```

779

780#### `+tree`

781

782Generate a recursive directory listing. Takes a path.

783

784```

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

786```

787

788### Hood

789

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

791

792`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts

793an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).

794

795```

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

797```

798

799`|link` / `|unlink` - Link / unlink a remote app. Accepts an

800Urbit name and an app name.

801

802```

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

804```

805

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

807No arguments.

808

809```

810~your-urbit:dojo> |mass

811```

812

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

814number of vane names.

815

816```

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

818```

819

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

821

822```

823~your-urbit:dojo> |reset

824```

825

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

827

828```

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

830```

831

832---

833

834### Dojo manual

835

836#### Sources and sinks

837

838A Dojo command is either a **source** or a **sink**. A source is just something

839that can be printed to your console or the result of some computation. A

840sink is an **effect**: a change to the filesystem, a network message, a

841change to your environment, or a typed message to an app.

842

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

844command.

845

846#### Sinks

847

848#### `=` - Set variable

849

850Set any environment variable:

851

852```

853~your-urbit:dojo> =foo 42

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

855

85644

857```

858

859Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

860variable in a `.hoon` file in this way.

861

862#### Special variables

863

864There are a few special variables that the Dojo maintains.

865

866#### `:` - Send to app

867

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

869

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

871

872```

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

874```

875

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

877

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

879

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

881

882```

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

884```

885

886The last component of the path is expected to be the mark (or mime

887type).

888

889#### `.` - Export to Unix

890

891Export a noun to Unix with `.`:

892

893```

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

895```

896

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

898

899This is very often used with `+solid`:

900

901```

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

903```

904

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

906

907### Sources

908

909#### `&` - Mark conversion

910

911Convert 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:

912

913```

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

915'<html><head></head><body><h1 id="hello">hello</h1></body></html>'

916```

917

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

919

920```

921~your-urbit:dojo>&hymn &udon ';h1#hello: hello'

922[[%html ~] [[%head ~] ~] [[%body ~] [g=[n=%h1 a=~[[n=%id v="hello"]]] c=~[[g=[n=%$ a=~[[n=%$ v="hello"]]] c=~]]] ~] ~]

923```