Urbit Operators
  • Urbit OS

    • Basics
    • Updates
    • Configuring S3 Storage
    • Shell
    • Filesystem
    • Star and Galaxy Operations
    • Ship Troubleshooting
    • Dojo Tools
    • Urbit ID

      • Overview
      • Using Bridge
      • Proxies
      • HD Wallet (Master Ticket)
      • Bridge Troubleshooting
      • Creating an Invite Pool
      • Guide to Factory Resets
      • Layer 2 for planets
      • Layer 2 for stars
      • Running Urbit

        • Runtime Reference
        • Cloud Hosting
        • Self-hosting S3 Storage with MinIO
        • Coturn Operator Guide
        Urbit Operators
        • Urbit OS

          • Basics
          • Updates
          • Configuring S3 Storage
          • Shell
          • Filesystem
          • Star and Galaxy Operations
          • Ship Troubleshooting
          • Dojo Tools
          • Urbit ID

            • Overview
            • Using Bridge
            • Proxies
            • HD Wallet (Master Ticket)
            • Bridge Troubleshooting
            • Creating an Invite Pool
            • Guide to Factory Resets
            • Layer 2 for planets
            • Layer 2 for stars
            • Running Urbit

              • Runtime Reference
              • Cloud Hosting
              • Self-hosting S3 Storage with MinIO
              • Coturn Operator Guide
              Operator's Manual/Urbit OS

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

              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 in the %base desk. For generators on other desks, you can use the syntax +desk!genname.

              +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

              You can change your code to a new randomly generated one by entering |code %reset. Please note that this will prevent Bridge from being able to derive your code in the future.

              +ls

              Similar to Unix ls. Accepts a path.

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

              +solid

              Compile the current state of the kernel and output a noun. Usually downloaded to a file in unix. This generator takes a series of desks to include as its argument. The first desk must be the base desk that contains the Arvo kernel, standard library and related files - typically %base.

              ~your-urbit:dojo> .urbit/pill +solid %base %garden %landscape %webterm %bitcoin

              +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 CLI app - may or may not be remote. Accepts an optional ship name and a mandatory app name.

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

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

              ~your-urbit:dojo> |mass

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

              ~your-urbit:dojo> |breload %clay %eyre

              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

              _ - Run a function

              Use _ to run a gate (or function):

              Write an arbitrary function and pass data to it:

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

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

              ~your-urbit:dojo> _|=([[email protected] 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

              Generators on desks other than %base can be run with the syntax +desk!generator.

              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/

              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
              0v27k.n4atp.fovm6.f7ggm.jdkn5.elct5.11tna.4qtid.g4so7.a1h6g.grp7u.qml4i.0ed1v.sl0r0.97d4b.6aepr.6v6qm.ls5ve.60kgb.j6521.2fqcb

              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.