:- :~ navhome/'/docs/' navuptwo/'true' next/'true' sort/'6' title/'Shell (Dojo)' == ;> # Shell (Dojo) 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](../../tutorials/hoon-ch1/hoon-ch1-3). 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 %/web ``` (`%` represents your current directory. For a complete explanation on urbit paths, see the [filesystem section](/docs/using/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 Retrives 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 %/web ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes ``` ##### +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 %/web ``` ### 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 ``` --- ## Manual ;h3(class "first child") 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 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 `.umd` file in `web`: ``` ~your-urbit:dojo> *%/web/foo/umd '# 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 `&`: ``` ~your-urbit:dojo> &html &md '# 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 %/web ~your-urbit:dojo> +ls % 404/hoon docs/ dojo/hoon lib/ listen/hoon md static/umd talk/ testing/umd tree/main/ unmark/ womb/ ``` ##### lib Current set of libraries (`/lib`) in your environment. Can be set with `/+`. Read / write. *Examples:* ``` ~your-urbit:dojo> /+ react ~your-urbit:dojo> :: now we can use arms from lib/react.hoon ~your-urbit:dojo> (react-vale:react %div) ``` ##### sur Current set of structures (`/sur`) in your environment. Can be set with `/-`. Read / write. *Examples:* ``` ~your-urbit:dojo> /- sole ~your-urbit:dojo> :: 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 :: produces ~2016.3.21..21.10.57..429a ``` ##### our The current urbit ship. Read-only. *Example:* ``` ~your-urbit:dojo> our :: produces ~your-urbit ``` ##### eny 512 bits of entropy. Read-only. *Example:* ``` ~your-urbit:dojo> eny :: produces \/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.